ISO 3166 Countries API

Q: Can I look up both two-letter and three-letter country codes?

Yes — /api/countries/lookup?code=DK and ?code=DNK return the same Denmark record, case-insensitively. A well-formed unknown code returns 404, never a nearby record.

Q: Can I filter the country list by continent or name?

REAL DATA

All 249 ISO 3166-1 countries and territories with codes, regions, capitals, currencies, languages, calling codes, flags and label-safe land points.

Authoritative reference data or standards computation

Base URL: /api/countries
Category: Geo & Reference
Capabilities: 2 routes
Last updated: July 30, 2026

Data source: ISO 3166-1 + UN M49; Natural Earth public-domain map points; countries-list 3.4.0 (MIT); country-coder 5.6.1 (ISC, Mayotte only)

GET /api/countries List all ISO 3166-1 entries (filterable by region and name) Returns a list

Returns the full 249-entry alphabetical table by default. Region and search filters compose; count limits the filtered result.

Live requestRuns against the public API

No key required

GET/api/countries

Request parameters

regiondefault any

Only return entries in this lowercase geographic region; any keeps every region.

search

Case- and diacritic-insensitive substring match against the common English name (aland finds Åland Islands).

Advanced response options6 options

countdefault all matches

Limit the number of returned records (1–100). Defaults to all matches.

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

formatdefault json

Response format: json envelope, ndjson (one record per line) or csv.

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 8 params · 13 fields · 4 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/countries"

const res = await fetch("https://randomapi.dev/api/countries");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/countries").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/countries"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 2

Parameter	Type	Default & allowed	Description
`region`	enum	default: any allowed: any \| africa \| americas \| asia \| europe \| oceania \| antarctic example: europe	Only return entries in this lowercase geographic region; any keeps every region.
`search`	string	allowed: 1 – 100 example: united	Case- and diacritic-insensitive substring match against the common English name (aland finds Åland Islands).

region enum

Only return entries in this lowercase geographic region; any keeps every region.

default: any

example: region=europe

search string

Case- and diacritic-insensitive substring match against the common English name (aland finds Åland Islands).

allowed: 1 – 100

example: search=united

Universal parameters Shared response and formatting options 6

Parameter	Type	Default & allowed	Description
`count`	int	default: all matches allowed: 1 – 100 example: 3	Limit the number of returned records (1–100). Defaults to all matches.
`fields`	list	example: name,code	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: longitude	Return all fields except these (comma-separated).
`format`	enum	default: json allowed: json \| ndjson \| csv example: csv	Response format: json envelope, ndjson (one record per line) or csv.
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

count int

Limit the number of returned records (1–100). Defaults to all matches.

default: all matches

allowed: 1 – 100

example: count=3

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=name,code

exclude list

Return all fields except these (comma-separated).

example: exclude=longitude

format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json

allowed: json | ndjson | csv

example: format=csv

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 13

Field	Type	Description	Example
`name`	string	Common English country or territory name.	Denmark
`code`	string	ISO 3166-1 alpha-2 code.	DK
`alpha3`	string	ISO 3166-1 alpha-3 code.	DNK
`numeric`	string	Three-digit ISO 3166-1 numeric code, kept as text to preserve leading zeroes.	208
`capital` nullable	string	Capital; multiple official seats are separated by semicolons. Null for territories without a capital.	Copenhagen
`region`	string	Lowercase geographic region: africa, americas, asia, europe, oceania or antarctic.	europe
`subregion` nullable	string	UN M49 geographic subregion where assigned; otherwise null.	Northern Europe
`currencyCode` nullable	string	Primary active ISO 4217 currency code. Null where no single active ISO currency is assigned.	DKK
`languages`	string[]	English labels normalized to the LOC ISO 639 Set 1 registry; Papiamento is included explicitly for Aruba and Curaçao despite having no Set 1 code.	["Danish"]
`callingCode` nullable	string	Primary international calling prefix. Shared numbering plans may include the destination prefix; null where none is assigned.	+45
`flagEmoji`	string	Unicode regional-indicator flag sequence for the alpha-2 code.	🇩🇰
`latitude`	float	Latitude of a label-safe point inside the largest/main land unit (WGS84), not the capital's latitude.	56
`longitude`	float	Longitude of a label-safe point inside the largest/main land unit (WGS84), not the capital's longitude.	10

name string

Common English country or territory name.

example: Denmark

code string

ISO 3166-1 alpha-2 code.

example: DK

alpha3 string

ISO 3166-1 alpha-3 code.

example: DNK

numeric string

Three-digit ISO 3166-1 numeric code, kept as text to preserve leading zeroes.

example: 208

capital string nullable

Capital; multiple official seats are separated by semicolons. Null for territories without a capital.

example: Copenhagen

region string

Lowercase geographic region: africa, americas, asia, europe, oceania or antarctic.

example: europe

subregion string nullable

UN M49 geographic subregion where assigned; otherwise null.

example: Northern Europe

currencyCode string nullable

Primary active ISO 4217 currency code. Null where no single active ISO currency is assigned.

example: DKK

languages string[]

English labels normalized to the LOC ISO 639 Set 1 registry; Papiamento is included explicitly for Aruba and Curaçao despite having no Set 1 code.

example: ["Danish"]

callingCode string nullable

Primary international calling prefix. Shared numbering plans may include the destination prefix; null where none is assigned.

example: +45

flagEmoji string

Unicode regional-indicator flag sequence for the alpha-2 code.

example: 🇩🇰

latitude float

Latitude of a label-safe point inside the largest/main land unit (WGS84), not the capital's latitude.

example: 56

longitude float

Longitude of a label-safe point inside the largest/main land unit (WGS84), not the capital's longitude.

example: 10

Documented examples

Build-generated requests and complete responses 4

The complete ISO table /api/countries

GET /api/countries

{
  "data": [
    {
      "name": "Afghanistan",
      "code": "AF",
      "alpha3": "AFG",
      "numeric": "004",
      "capital": "Kabul",
      "region": "asia",
      "subregion": "Southern Asia",
      "currencyCode": "AFN",
      "languages": [
        "Pashto",
        "Persian",
        "Turkmen",
        "Uzbek"
      ],
      "callingCode": "+93",
      "flagEmoji": "🇦🇫",
      "latitude": 34.3332,
      "longitude": 66.6552
    },
    {
      "name": "Åland Islands",
      "code": "AX",
      "alpha3": "ALA",
      "numeric": "248",
      "capital": "Mariehamn",
      "region": "europe",
      "subregion": "Northern Europe",
      "currencyCode": "EUR",
      "languages": [
        "Swedish"
      ],
      "callingCode": "+358",
      "flagEmoji": "🇦🇽",
      "latitude": 60.1611,
      "longitude": 19.8774
    },
    {
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Every European entry /api/countries?region=europe

GET /api/countries?region=europe

{
  "data": [
    {
      "name": "Åland Islands",
      "code": "AX",
      "alpha3": "ALA",
      "numeric": "248",
      "capital": "Mariehamn",
      "region": "europe",
      "subregion": "Northern Europe",
      "currencyCode": "EUR",
      "languages": [
        "Swedish"
      ],
      "callingCode": "+358",
      "flagEmoji": "🇦🇽",
      "latitude": 60.1611,
      "longitude": 19.8774
    },
    {
      "name": "Albania",
      "code": "AL",
      "alpha3": "ALB",
      "numeric": "008",
      "capital": "Tirana",
      "region": "europe",
      "subregion": "Southern Europe",
      "currencyCode": "ALL",
      "languages": [
        "Albanian"
      ],
      "callingCode": "+355",
      "flagEmoji": "🇦🇱",
      "latitude": 40.6449,
      "longitude": 20.1102
    },
    {
      "name": "Andorra",
      "code": "AD",
      "alpha3": "AND",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Find countries named United /api/countries?search=united

GET /api/countries?search=united

{
  "data": [
    {
      "name": "United Arab Emirates",
      "code": "AE",
      "alpha3": "ARE",
      "numeric": "784",
      "capital": "Abu Dhabi",
      "region": "asia",
      "subregion": "Western Asia",
      "currencyCode": "AED",
      "languages": [
        "Arabic"
      ],
      "callingCode": "+971",
      "flagEmoji": "🇦🇪",
      "latitude": 23.4791,
      "longitude": 54.5322
    },
    {
      "name": "United Kingdom",
      "code": "GB",
      "alpha3": "GBR",
      "numeric": "826",
      "capital": "London",
      "region": "europe",
      "subregion": "Northern Europe",
      "currencyCode": "GBP",
      "languages": [
        "English"
      ],
      "callingCode": "+44",
      "flagEmoji": "🇬🇧",
      "latitude": 52.4815,
      "longitude": -1.2582
    },
    {
      "name": "United States",
      "code": "US",
      "alpha3": "USA",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

First 10 Asian codes as CSV /api/countries?region=asia&count=10&format=csv&fields=name,code,alpha3

GET /api/countries?region=asia&count=10&format=csv&fields=name,code,alpha3

name,code,alpha3
Afghanistan,AF,AFG
Armenia,AM,ARM
Azerbaijan,AZ,AZE
Bahrain,BH,BHR
Bangladesh,BD,BGD
Bhutan,BT,BTN
Brunei,BN,BRN
Cambodia,KH,KHM
China,CN,CHN
Cyprus,CY,CYP

GET /api/countries/lookup Look up one country or territory by alpha-2 or alpha-3 code Single-record lookup

Accepts a 2- or 3-letter ISO 3166-1 code, case-insensitively. Unknown codes are explicit 404s with a nearby-code hint when available.

Route reference

Code, request parameters, response fields and verified examples 5 params · 13 fields · 3 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/countries/lookup?code=DK"

const res = await fetch("https://randomapi.dev/api/countries/lookup?code=DK");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/countries/lookup?code=DK").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/countries/lookup?code=DK"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 1

Parameter	Type	Default & allowed	Description
`code` required	string	allowed: 2 – 3 example: DK	ISO 3166-1 alpha-2 or alpha-3 code, case-insensitive (DK or DNK).

code string required

ISO 3166-1 alpha-2 or alpha-3 code, case-insensitive (DK or DNK).

allowed: 2 – 3

example: code=DK

Universal parameters Shared response and formatting options 4

Parameter	Type	Default & allowed	Description
`fields`	list	example: name,code	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: longitude	Return all fields except these (comma-separated).
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=name,code

exclude list

Return all fields except these (comma-separated).

example: exclude=longitude

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 13

Field	Type	Description	Example
`name`	string	Common English country or territory name.	Denmark
`code`	string	ISO 3166-1 alpha-2 code.	DK
`alpha3`	string	ISO 3166-1 alpha-3 code.	DNK
`numeric`	string	Three-digit ISO 3166-1 numeric code, kept as text to preserve leading zeroes.	208
`capital` nullable	string	Capital; multiple official seats are separated by semicolons. Null for territories without a capital.	Copenhagen
`region`	string	Lowercase geographic region: africa, americas, asia, europe, oceania or antarctic.	europe
`subregion` nullable	string	UN M49 geographic subregion where assigned; otherwise null.	Northern Europe
`currencyCode` nullable	string	Primary active ISO 4217 currency code. Null where no single active ISO currency is assigned.	DKK
`languages`	string[]	English labels normalized to the LOC ISO 639 Set 1 registry; Papiamento is included explicitly for Aruba and Curaçao despite having no Set 1 code.	["Danish"]
`callingCode` nullable	string	Primary international calling prefix. Shared numbering plans may include the destination prefix; null where none is assigned.	+45
`flagEmoji`	string	Unicode regional-indicator flag sequence for the alpha-2 code.	🇩🇰
`latitude`	float	Latitude of a label-safe point inside the largest/main land unit (WGS84), not the capital's latitude.	56
`longitude`	float	Longitude of a label-safe point inside the largest/main land unit (WGS84), not the capital's longitude.	10

name string

Common English country or territory name.

example: Denmark

code string

ISO 3166-1 alpha-2 code.

example: DK

alpha3 string

ISO 3166-1 alpha-3 code.

example: DNK

numeric string

Three-digit ISO 3166-1 numeric code, kept as text to preserve leading zeroes.

example: 208

capital string nullable

Capital; multiple official seats are separated by semicolons. Null for territories without a capital.

example: Copenhagen

region string

Lowercase geographic region: africa, americas, asia, europe, oceania or antarctic.

example: europe

subregion string nullable

UN M49 geographic subregion where assigned; otherwise null.

example: Northern Europe

currencyCode string nullable

Primary active ISO 4217 currency code. Null where no single active ISO currency is assigned.

example: DKK

languages string[]

English labels normalized to the LOC ISO 639 Set 1 registry; Papiamento is included explicitly for Aruba and Curaçao despite having no Set 1 code.

example: ["Danish"]

callingCode string nullable

Primary international calling prefix. Shared numbering plans may include the destination prefix; null where none is assigned.

example: +45

flagEmoji string

Unicode regional-indicator flag sequence for the alpha-2 code.

example: 🇩🇰

latitude float

Latitude of a label-safe point inside the largest/main land unit (WGS84), not the capital's latitude.

example: 56

longitude float

Longitude of a label-safe point inside the largest/main land unit (WGS84), not the capital's longitude.

example: 10

Documented examples

Build-generated requests and complete responses 3

Denmark by alpha-2 /api/countries/lookup?code=DK

GET /api/countries/lookup?code=DK

{
  "data": {
    "name": "Denmark",
    "code": "DK",
    "alpha3": "DNK",
    "numeric": "208",
    "capital": "Copenhagen",
    "region": "europe",
    "subregion": "Northern Europe",
    "currencyCode": "DKK",
    "languages": [
      "Danish"
    ],
    "callingCode": "+45",
    "flagEmoji": "🇩🇰",
    "latitude": 55.942,
    "longitude": 8.9969
  },
  "meta": {
    "endpoint": "countries",
    "route": "/lookup",
    "params": {
      "code": "DK"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Denmark by lowercase alpha-3 /api/countries/lookup?code=dnk

GET /api/countries/lookup?code=dnk

{
  "data": {
    "name": "Denmark",
    "code": "DK",
    "alpha3": "DNK",
    "numeric": "208",
    "capital": "Copenhagen",
    "region": "europe",
    "subregion": "Northern Europe",
    "currencyCode": "DKK",
    "languages": [
      "Danish"
    ],
    "callingCode": "+45",
    "flagEmoji": "🇩🇰",
    "latitude": 55.942,
    "longitude": 8.9969
  },
  "meta": {
    "endpoint": "countries",
    "route": "/lookup",
    "params": {
      "code": "DNK"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

Japan's calling code and currency /api/countries/lookup?code=JPN&fields=name,callingCode,currencyCode

GET /api/countries/lookup?code=JPN&fields=name,callingCode,currencyCode

{
  "data": {
    "name": "Japan",
    "callingCode": "+81",
    "currencyCode": "JPY"
  },
  "meta": {
    "endpoint": "countries",
    "route": "/lookup",
    "params": {
      "code": "JPN"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

The complete set of 249 officially assigned ISO 3166-1 entries — countries and dependent territories — with alpha-2, alpha-3 and zero-padded numeric codes. The user-assigned XK code is deliberately excluded because it is not an officially assigned ISO 3166-1 entry.

The code fields are checked against ISO 3166-1 and UN Statistics M49. region and subregion follow M49's statistical geography where it assigns one; Antarctica and Taiwan use their conventional geographic placement where the M49 table does not provide a grouping. This means statistically assigned territories can appear under a region that differs from their physical continent — the API returns the reference classification rather than silently inventing one.

Codes and names are reproduced exactly as published by the source cited on this page; randomapi.dev takes no position on the sovereignty or territorial status of any country, territory or subdivision, and the presence, absence or nesting of any entry implies none.

The two reference endpoints built on this same key space state it identically: /api/country-borders for land adjacency and /api/country-subdivisions for ISO 3166-2.

Supplemental fields are deliberately explicit about their limits:

capital is null when an entry has no capital; multiple official seats are separated by semicolons.
currencyCode is one primary active ISO 4217 code, sourced from this project's currency registry; it is null where no single code is assigned.
callingCode is the primary international calling prefix; shared plans can include a destination prefix (for example Anguilla's +1264).
languages are normalized to the Library of Congress ISO 639 Set 1 registry used by the languages endpoint. Papiamento is the explicit exception for Aruba and Curaçao because it has no Set 1 alpha-2 code.
latitude and longitude are label-safe points inside the largest/main land unit, not arithmetic centroids, capital coordinates or boundary geometry. This keeps long, narrow and multi-territory records pinned to useful land rather than the ocean.
coordinates use pinned Natural Earth public-domain geometry/label points for 248 entries; Mayotte uses pinned country-coder ISC geometry. Names, capitals, language mappings and calling prefixes come from pinned countries-list MIT data. Exact versions, commits, derivation and license notices are recorded with the bundled dataset — there is no copyleft/share-alike dependency.

The list route is alphabetical, region genuinely restricts every result, and search is case- and diacritic-insensitive. The lookup route accepts either alpha-2 or alpha-3, case-insensitively. Unknown codes return a 404 with a nearby-code hint when possible — never a substitute country.

Use it for

Populate an ISO-backed country selector with display names, codes and flags
Validate alpha-2 or alpha-3 input and retrieve one exact country record
Group countries and territories by UN M49 region or subregion
Resolve a country code to a primary currency, calling code or useful main-territory map pin

Frequently asked questions

Practical answers about this endpoint 4

Does this API include every ISO 3166-1 country code?

Yes — it contains all 249 officially assigned alpha-2, alpha-3 and numeric entries. The user-assigned XK code is excluded because it is not an official ISO 3166-1 assignment.

Can I look up both two-letter and three-letter country codes?

Yes — /api/countries/lookup?code=DK and ?code=DNK return the same Denmark record, case-insensitively. A well-formed unknown code returns 404, never a nearby record.

Can I filter the country list by continent or name?

Are the latitude and longitude capital coordinates?

No — each is a deterministic label-safe point inside the entry's largest or main land unit, designed for useful lightweight map pins. The capital is separate, and entries without one return null.

Standards & references

Primary sources behind the contract

Useful next tools in the catalog

World Cities API REAL DATA

6,300+ world cities from a pinned GeoNames snapshot: coordinates, IANA timezone, population and capital flag — filter by country, size, name or distance.

Timezone Database API REAL DATA

Live IANA offsets, DST transitions, local-time ambiguity resolution and exact instant conversion — no guessed wall-clock mappings.

ISO 4217 Currency Codes API REAL DATA

Every active ISO 4217 currency — code, name, symbol, minor-unit decimals and the countries using it. Search the list or look up one code, with honest 404s.

Public Holidays API REAL DATA

Real public holidays for 61 countries, computed from official national rules — list a year, check a date, or get the next upcoming holiday.

Country Land Borders & Neighbours API REAL DATA

Land neighbours for all 250 countries and territories, published border lengths in km, the 45 landlocked entries and shortest land-border paths.

ISO 3166-2 Subdivisions API — States, Provinces & Regions REAL DATA

ISO 3166-2 states, provinces and regions: 5,046 subdivision codes for 200 countries, with English names, parent codes and an auditable per-country index.

GET /api/countries List all ISO 3166-1 entries (filterable by region and name) Returns a list

Request parameters

Response

Route reference

Documented examples

GET /api/countries/lookup Look up one country or territory by alpha-2 or alpha-3 code Single-record lookup

Request parameters

Response

Route reference

Documented examples

About this API

Coverage & behavior

Use it for

Frequently asked questions

Standards & references

Related APIs