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

The COUNTRY_CODES dictionary in 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/master/make_playlist.py) at the module level. The dictionary contains approximately 50+ entries covering countries from Albania to Venezuela.

# 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 → "albania"
• bosnia_and_herzegovina.md → "bosnia_and_herzegovina"
• 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 processes the repository's channel lists, it extracts the ISO code through a straightforward lookup mechanism:

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:

# 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:

# 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:

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 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), then add a corresponding entry to the COUNTRY_CODES dictionary in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}