# How the COUNTRY_CODES Dictionary Maps Country Names to ISO Codes in Free-TV/IPTV

> Learn how the COUNTRY_CODES dictionary in Free-TV/IPTV maps country names to ISO codes using filename segments as keys and two-letter country codes as values in make_playlist.py.

- Repository: [Free TV/IPTV](https://github.com/Free-TV/IPTV)
- Tags: internals
- Published: 2026-06-17

---

**The `COUNTRY_CODES` dictionary in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) maps normalized, lower-case country names to ISO 3166-1 alpha-2 codes by using filename segments from markdown files as keys and two-letter country codes as values.**

The Free-TV/IPTV repository automates playlist generation through a Python script that converts country-specific markdown lists into standardized M3U playlists. Central to this process is a hardcoded dictionary that bridges human-readable country names with official ISO country codes. Understanding how the **COUNTRY_CODES** dictionary maps country names to ISO codes reveals the normalization logic that ensures every channel receives the correct `tvg-country` attribute.

## Where COUNTRY_CODES Is Defined

The mapping resides in [[`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py)](https://github.com/Free-TV/IPTV/blob/master/make_playlist.py) at the module level. The dictionary contains approximately 50+ entries covering countries from Albania to Venezuela.

```python

# make_playlist.py

COUNTRY_CODES = {
    "albania": "AL",
    "andorra": "AD",
    "argentina": "AR",
    "armenia": "AM",
    "australia": "AU",
    "austria": "AT",
    "azerbaijan": "AZ",
    "belarus": "BY",
    "belgium": "BE",
    "bosnia_and_herzegovina": "BA",
    "brazil": "BR",
    "bulgaria": "BG",
    ...
    "usa": "US",
    "venezuela": "VE",
}

```

## Key Structure and Normalization

### Key Format: Lower-Case and Underscore-Separated

Each **key** derives directly from the filename of a country-specific markdown list in the `lists/` directory. The script strips the `.md` extension and uses the remaining string as the lookup key.

- [`albania.md`](https://github.com/Free-TV/IPTV/blob/main/albania.md) → `"albania"`
- [`bosnia_and_herzegovina.md`](https://github.com/Free-TV/IPTV/blob/main/bosnia_and_herzegovina.md) → `"bosnia_and_herzegovina"`
- [`united_kingdom.md`](https://github.com/Free-TV/IPTV/blob/main/united_kingdom.md) → `"united_kingdom"`

This normalization ensures filesystem compatibility while maintaining human readability.

### Value Format: ISO 3166-1 Alpha-2

Every **value** follows the **ISO 3166-1 alpha-2** standard, providing exactly two uppercase letters representing the country code. These codes populate the `tvg-country` attribute in generated M3U playlists.

## How the Mapping Is Used

When [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) processes the repository's channel lists, it extracts the ISO code through a straightforward lookup mechanism:

```python
country_key = filename[:-3]               # strip ".md"

country_code = COUNTRY_CODES.get(country_key, "")

```

The retrieved `country_code` then passes into the **Channel** class constructor. Within `Channel.to_m3u_line()`, the code injects this value as the `tvg-country` attribute:

```python

# Example: processing Italy

country_key = "italy"
iso = COUNTRY_CODES.get(country_key, "")
channel = Channel(group="Italy", line=line, country_code=iso)
print(channel.to_m3u_line())

# Output contains: tvg-country="IT"

```

If a country markdown file exists without a corresponding entry in `COUNTRY_CODES`, the `get()` method returns an empty string, and the generated playlist line omits the country attribute.

## Practical Code Examples

Retrieve an ISO code directly from the dictionary:

```python

# Direct lookup

code = COUNTRY_CODES.get("italy")
print(code)   # → "IT"

# Safe lookup with default for missing entries

unknown = COUNTRY_CODES.get("fictional_country", "")
print(unknown)   # → ""

```

Integrate the mapping into playlist generation workflow:

```python
import os

def process_country_file(filepath):
    filename = os.path.basename(filepath)        # e.g., "germany.md"

    country_key = filename[:-3]                  # "germany"

    iso_code = COUNTRY_CODES.get(country_key, "") # "DE"

    
    # Use the code when constructing channel entries

    return iso_code

```

## Summary

- **COUNTRY_CODES** lives in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) and maps normalized country names to ISO codes.
- **Keys** use lower-case, underscore-separated filenames derived from `lists/*.md` files (e.g., `"bosnia_and_herzegovina"`).
- **Values** are strictly ISO 3166-1 alpha-2 codes (e.g., `"BA"`, `"DE"`).
- The script extracts the country key by stripping the `.md` extension and performs a dictionary lookup via `COUNTRY_CODES.get(country_key, "")`.
- Retrieved codes populate the `tvg-country` attribute in generated M3U playlist lines through the `Channel.to_m3u_line()` method.

## Frequently Asked Questions

### What happens if a country is missing from the COUNTRY_CODES dictionary?

The script calls `COUNTRY_CODES.get(country_key, "")`, which returns an empty string for missing keys. Consequently, the generated M3U playlist line will not include a `tvg-country` attribute for channels from that country.

### Why does the dictionary use underscore-separated names instead of spaces?

The keys must match the filenames of markdown lists in the `lists/` directory. Filesystems typically avoid spaces in favor of underscores or hyphens for compatibility. The Free-TV/IPTV repository uses snake_case to ensure consistent file naming and easy parsing without complex string transformations.

### Which ISO standard does the COUNTRY_CODES dictionary follow?

The dictionary uses **ISO 3166-1 alpha-2**, the two-letter country code standard. Every value in the dictionary consists of exactly two uppercase letters (e.g., `"US"` for USA, `"GB"` for United Kingdom) that comply with this international standard for country identification.

### Can I add a new country to the playlist generation?

Yes. Create a new markdown file in `lists/` with an underscore-separated name (e.g., [`new_country.md`](https://github.com/Free-TV/IPTV/blob/main/new_country.md)), then add a corresponding entry to the `COUNTRY_CODES` dictionary in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) mapping the filename root to the appropriate ISO 3166-1 alpha-2 code. The script will automatically pick up the new list and inject the country code into the generated playlist.