Mastering ISO Codes in Python: A Practical Guide with reference.do

Dealing with standardized datasets like country codes, currencies, and languages is a universal task for developers. Whether you're building a checkout form, localizing an application, or analyzing geographic data, you need access to this information. The common approach? Find a CSV, copy-paste a list into a constant, or install a library that's likely already out of date. These methods are brittle, hard to maintain, and create data silos across your services.

There's a better way.

This guide will show you how to master ISO codes in Python by treating them not as static files, but as what they are: reference data. We'll use reference.do, a simple API for accessing managed reference data, to build cleaner, more reliable, and easier-to-maintain applications.

The Problem with Static Data

Let's say you need a list of countries for a dropdown menu. You might be tempted to hardcode it:

# The "don't do this" example
COUNTRIES = [
    {"code": "US", "name": "United States"},
    {"code": "CA", "name": "Canada"},
    {"code": "MX", "name": "Mexico"},
    # ... and 246 more entries you have to find and paste
]

This seems simple at first, but the problems pile up quickly:

• Inconsistency: What happens when another microservice in your stack needs the same list? You copy it. Now you have two lists to maintain.
• Updates are a Pain: Countries change names (e.g., Turkey to Türkiye), new currency codes are adopted. Updating these lists requires a code change, a PR, and a new deployment for every single application that uses it.
• Incomplete Data: Your list has country codes and names. What about their official currency? Or their language codes? You're now managing three separate, potentially out-of-sync lists.
• Bloat: You've just added hundreds of lines of static data to your application code.

This is a classic reference data management problem. The solution is to centralize this data and access it via a single source of truth.

Your Single Source of Truth: reference.do

reference.do provides foundational, slow-changing data as a service. Instead of managing static datasets in every application, you can access, query, and integrate standard and custom reference data through one simple, reliable API.

Think of it as Data. On. Demand.

Let's see how easy it is to work with ISO codes in Python using reference.do.

Getting Started

1. Get your API Key: First, sign up on reference.do to get your free API key.
2. Set up your environment: We'll use the popular requests library to connect to the API. If you don't have it, install it:

   pip install requests
   

   For security, it's best practice to store your API key as an environment variable.

   export DO_API_KEY="your_api_key_here"
   

Example 1: Fetching ISO 4217 Currency Codes

Need to populate a currency selector or validate a currency symbol? A single API call gets you a complete, up-to-date list of all official ISO 4217 currencies.

import os
import requests
import json

# Your API key from reference.do
API_KEY = os.environ.get("DO_API_KEY")
BASE_URL = "https://api.reference.do/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

try:
    # Get a list of all ISO 4217 currencies
    response = requests.get(f"{BASE_URL}/reference/iso-4217", headers=headers)
    response.raise_for_status()  # Raises an HTTPError for bad responses (4xx or 5xx)

    currencies = response.json()
    print(json.dumps(currencies, indent=2))

except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err}")
except Exception as err:
    print(f"An error occurred: {err}")

The output is a clean, ready-to-use JSON array:

[
  {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$"
  },
  {
    "code": "EUR",
    "name": "Euro",
    "symbol": "€"
  },
  {
    "code": "JPY",
    "name": "Japanese Yen",
    "symbol": "¥"
  },
  {
    "code": "GBP",
    "name": "Pound Sterling",
    "symbol": "£"
  }
  // ... and many more
]

No more outdated lists or incomplete data.

Example 2: Fetching ISO 3166 Country Codes

Let's get that country list for your dropdown. We just change the dataset ID in the URL.

# ... (using the same setup as before)

try:
    # Get a list of all ISO 3166-1 Alpha-2 country codes
    response = requests.get(f"{BASE_URL}/reference/iso-3166", headers=headers)
    response.raise_for_status()

    countries = response.json()
    
    # Let's find a specific country
    canada = next((country for country in countries if country["alpha2"] == "CA"), None)
    print(json.dumps(canada, indent=2))

except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err}")

This will fetch the full list and then we can easily find and print the data for Canada:

{
  "name": "Canada",
  "alpha2": "CA",
  "alpha3": "CAN",
  "numeric": "124"
}

Example 3: Fetching ISO 639 Language Codes

Need to build a language selector for your application's localization settings? It's the same simple pattern.

# ... (using the same setup as before)

try:
    # Get a list of all ISO 639-1 language codes
    response = requests.get(f"{BASE_URL}/reference/iso-639", headers=headers)
    response.raise_for_status()

    languages = response.json()
    print(json.dumps(languages[:5], indent=2)) # Print first 5 for brevity

except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err}")

And you get beautifully structured language data:

[
  {
    "name": "Afar",
    "alpha2": "aa",
    "alpha3": "aar"
  },
  {
    "name": "Abkhazian",
    "alpha2": "ab",
    "alpha3": "abk"
  },
  {
    "name": "Avestan",
    "alpha2": "ae",
    "alpha3": "ave"
  },
  {
    "name": "Afrikaans",
    "alpha2": "af",
    "alpha3": "afr"
  },
  {
    "name": "Akan",
    "alpha2": "ak",
    "alpha3": "aka"
  }
]

Beyond Standard Codes: Your Own Data

The power of reference.do extends beyond public standards like ISO codes. You can upload, manage, version, and query your own proprietary reference datasets—like a list of your internal store locations or product categories—right alongside the public ones, all through the same simple API. This creates a unified layer for all reference data in your organization.

Stop Managing Data, Start Building Apps

By moving from static files to a centralized API, you gain:

• A Single Source of Truth: No more data duplication or inconsistencies. Every application gets the same, correct data.
• Effortless Updates: ISO standards evolve. With reference.do, the data is kept current for you. No code changes required.
• Simplified Code: Your application code becomes cleaner, lighter, and more focused on its core logic.
• Seamless Integration: A unified API for all reference data, public or custom, makes building new features and services faster and more reliable.

Ready to stop chasing CSVs and start writing cleaner code? Sign up for a free API key at reference.do and make data management the easiest part of your job.