# How Country Codes Are Mapped to ISO Codes in IPTV Playlists

> Learn how Free-TV/IPTV maps country codes to ISO codes in playlists. Discover the centralized dictionary in make_playlist.py that standardizes tvg-country attributes for M3U generation.

- Repository: [Free TV/IPTV](https://github.com/Free-TV/IPTV)
- Tags: how-to-guide
- Published: 2026-06-26

---

**The Free-TV/IPTV repository maps country identifiers to ISO 3166-1 alpha-2 codes using a centralized `COUNTRY_CODES` dictionary in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py), which translates Markdown filenames into standardized `tvg-country` attributes for M3U playlist generation.**

The Free-TV/IPTV project maintains curated television channel lists organized by country in the `lists/` directory. Understanding how country codes are mapped to ISO codes in IPTV playlists is essential for developers customizing the playlist generator or verifying regional metadata accuracy. The mapping occurs through a single Python dictionary that bridges human-readable filenames with machine-standard ISO 3166-1 alpha-2 codes.

## The COUNTRY_CODES Dictionary Structure

At the core of the mapping system lies the **`COUNTRY_CODES`** dictionary defined 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) (lines 6–90). This data structure maps lowercase, underscore-separated country identifiers to their corresponding two-letter ISO codes.

The dictionary keys reflect the Markdown filenames stored in the `lists/` directory, such as `usa`, `canada`, `south_korea`, or `uk`. The values provide the standard ISO 3166-1 alpha-2 codes used internationally for region identification.

Common mappings include:

- `albania` → `AL`
- `canada` → `CA`
- `usa` → `US`
- `uk` → `GB`
- `spain` → `ES`
- `turkey` → `TR`

## Extracting Country Keys from Filenames

The playlist generator processes each `.md` file in the `lists/` directory by extracting the base filename to create a lookup key. The script removes the file extension and uses the resulting string as the `country_key` for dictionary access.

```python

# From make_playlist.py (lines 44-46)

country_key = filename[:-3]  # Strips '.md' extension

group = country_key.replace("_", " ").title()
country_code = COUNTRY_CODES.get(country_key, "")

```

This approach ensures that filenames like [`south_korea.md`](https://github.com/Free-TV/IPTV/blob/main/south_korea.md) are normalized to the key `south_korea`, which then retrieves the ISO code `KR` from the dictionary.

## Generating the tvg-country Attribute

Once the ISO code is retrieved, the generator injects it into the M3U playlist format through the **`Channel.to_m3u_line`** method. According to the source code in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py), this method constructs the `tvg-country` attribute only when a valid country code exists.

```python

# From Channel.to_m3u_line (line 15)

country = f' tvg-country="{self.country_code}"' if self.country_code else ""

```

This conditional formatting ensures that channels with unrecognized country keys—returning empty strings from the dictionary—do not generate malformed attributes in the final M3U output.

## Practical Implementation Example

Developers can import and utilize the `COUNTRY_CODES` dictionary directly to verify mappings or build custom tooling:

```python
from make_playlist import COUNTRY_CODES

def iso_for_file(filename: str) -> str:
    """Convert Markdown filename to ISO country code."""
    key = filename.rstrip('.md').lower()
    return COUNTRY_CODES.get(key, "")

# Usage examples

print(iso_for_file("usa.md"))          # → US

print(iso_for_file("uk.md"))           # → GB

print(iso_for_file("south_korea.md"))  # → KR

```

The complete playlist generation workflow combines these elements: file discovery, key extraction, ISO lookup via `COUNTRY_CODES.get(country_key, "")` (lines 44–46), and M3U line construction with proper attribute formatting.

## Summary

- The **Free-TV/IPTV** repository uses a centralized `COUNTRY_CODES` dictionary in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) to map internal country identifiers to ISO 3166-1 alpha-2 codes.
- Country keys are derived from Markdown filenames by stripping the `.md` extension and matching against lowercase, underscore-separated keys.
- The `COUNTRY_CODES.get(country_key, "")` lookup (lines 44–46) provides the ISO code used in the `tvg-country` attribute.
- The `Channel.to_m3u_line` method conditionally formats the `tvg-country` attribute to ensure valid M3U output.

## Frequently Asked Questions

### Where is the country code mapping defined in the Free-TV/IPTV repository?

The mapping is defined in the `COUNTRY_CODES` dictionary located 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) between lines 6 and 90. This dictionary contains all country identifier-to-ISO code translations used during playlist generation.

### What happens if a country filename is not in the COUNTRY_CODES dictionary?

If a Markdown filename does not match any key in `COUNTRY_CODES`, the `get()` method returns an empty string. The `Channel.to_m3u_line` method checks for this empty value and omits the `tvg-country` attribute entirely, preventing invalid M3U syntax.

### Why does the UK map to GB instead of UK in the ISO codes?

The repository follows the ISO 3166-1 alpha-2 standard, which assigns `GB` as the official code for the United Kingdom of Great Britain and Northern Ireland. While `UK` is reserved and not used, the `COUNTRY_CODES` dictionary correctly maps the internal `uk` filename key to the standard `GB` code.

### Can I add custom country codes to the mapping?

Yes, you can extend the `COUNTRY_CODES` dictionary in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) by adding new key-value pairs where the key matches your Markdown filename (lowercase, underscore-separated) and the value is the valid two-letter ISO code. The playlist generator will automatically include these in the `tvg-country` attributes.