Complete Guide to ISO Country Codes (ISO 3166)

ISO country codes are a cornerstone of international software development. Whether you're building e-commerce platforms, travel apps, or data pipelines, you'll inevitably encounter ISO 3166—the international standard for country codes. This guide explains everything you need to know, including how to query ISO codes using CountryDataAPI.

What is ISO 3166?

ISO 3166 is a standard published by the International Organization for Standardization (ISO) that defines internationally recognized codes for countries and their subdivisions. There are three main parts:

• ISO 3166-1 — Codes for countries and dependent territories
• ISO 3166-2 — Codes for subdivisions (states, provinces, regions)
• ISO 3166-3 — Codes for formerly used country names

ISO 3166-1 Alpha-2 Codes

Alpha-2 codes are two-letter country codes and the most widely used format. Examples:

• US — United States
• ES — Spain
• PT — Portugal
• DE — Germany
• FR — France
• BR — Brazil
• JP — Japan
• CN — China

Alpha-2 codes are used in domain extensions (.us, .es), language tags (en-US), payment systems, and virtually all REST APIs that deal with countries.

ISO 3166-1 Alpha-3 Codes

Alpha-3 codes are three-letter codes. They are more unique than alpha-2 codes (less risk of collision) and are used in passports, banking, and the UN system. Examples:

• USA — United States
• ESP — Spain
• PRT — Portugal
• DEU — Germany
• FRA — France
• BRA — Brazil

ISO 3166-1 Numeric Codes

Numeric codes are three-digit numbers assigned to each country. They are particularly useful in systems that cannot handle alphabetic characters. Examples:

• 840 — United States
• 724 — Spain
• 620 — Portugal
• 276 — Germany

How to Query Countries by ISO Code Using CountryDataAPI

CountryDataAPI provides a dedicated endpoint to look up a country by its ISO code:

GET https://api.countrydataapi.com/v1/countries/by-code?code=US

You can pass either alpha-2, alpha-3, or numeric codes:

// JavaScript - Fetch a country by ISO alpha-2 code
const response = await fetch(
  'https://api.countrydataapi.com/v1/countries/by-code?code=DE',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
);
const country = await response.json();
console.log(country.name); // "Germany"
console.log(country.iso3); // "DEU"
console.log(country.numeric_code); // "276"

The response includes all three ISO code formats, along with other useful data:

{
  "name": "Germany",
  "iso2": "DE",
  "iso3": "DEU",
  "numeric_code": "276",
  "phone_code": "+49",
  "currency": "EUR",
  "currency_symbol": "€",
  "region": "Europe",
  "subregion": "Western Europe",
  "flag": "🇩🇪",
  "timezones": ["Europe/Berlin"]
}

Practical Use Cases

Storing Country Data in Databases

When storing country data in a relational database, use the alpha-2 code as a foreign key—it's short (2 chars), human-readable, and universally recognized:

CREATE TABLE users (
  id INT PRIMARY KEY,
  email VARCHAR(255),
  country_code CHAR(2),  -- ISO 3166-1 alpha-2
  FOREIGN KEY (country_code) REFERENCES countries(iso2)
);

Validating User Input

When users submit country codes, validate them against the ISO standard using the API:

const isValidCountryCode = async (code) => {
  try {
    const res = await fetch(
      `https://api.countrydataapi.com/v1/countries/by-code?code=${code}`,
      { headers: { 'x-api-key': process.env.API_KEY } }
    );
    return res.ok;
  } catch {
    return false;
  }
};

Locale Detection and i18n

ISO alpha-2 codes map directly to IETF language tags. Use them to build locale strings:

const getLocale = (languageCode, countryCode) =>
  `${languageCode}-${countryCode}`;
// e.g., getLocale('en', 'US') => 'en-US'
// e.g., getLocale('pt', 'BR') => 'pt-BR'

Getting All Countries with ISO Codes

To retrieve the full list of countries with all their ISO codes:

const response = await fetch(
  'https://api.countrydataapi.com/v1/countries/all',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const countries = await response.json();
// Build a lookup map for fast access
const countryByIso2 = Object.fromEntries(
  countries.map(c => [c.iso2, c])
);

Summary

ISO 3166 country codes are essential for any application dealing with international data. Use alpha-2 for most use cases, alpha-3 for banking and documents, and numeric for legacy systems. CountryDataAPI provides all three formats in a single API call, along with phone codes, currencies, timezones, and more.