ISO 3166 Countries API

REAL DATA

All 249 ISO 3166-1 countries and territories: codes, capitals, currencies, languages, area in km², continent, ccTLD, calling codes, flags and map points.

Authoritative reference data or standards computation

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

Data sources · 2: 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)
GeoNames countryInfo.txt (CC BY 4.0) — area, continent, ccTLD and language tags

GET /api/countries List all ISO 3166-1 entries (filter by region, continent, area or name) Returns a list

Returns the full 249-entry alphabetical table by default. Region, continent, area-bound and search filters all compose; sort reorders the result and count limits it.

Live requestRuns against the public API

No key required

GET/api/countries

Request parameters

regiondefault any

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

continentdefault any

Only return entries on this GeoNames physical continent (AF, AN, AS, EU, NA, OC, SA); any keeps every continent. Distinct from region: Cyprus is region asia but continent EU.

search

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

minArea

Only return entries whose areaSqKm is at least this many square kilometres. The entry with no published area is excluded whenever this or maxArea is set.

maxArea

Only return entries whose areaSqKm is at most this many square kilometres. Must be ≥ minArea when both are given; the entry with no published area is excluded whenever either bound is set.

sortdefault name

Ordering of the filtered list: name is the default alphabetical order; area-desc and area-asc sort by areaSqKm, breaking ties alphabetically and placing unknown-area entries last in both directions.

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 12 params · 17 fields · 7 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 6

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 UN M49 geographic region; any keeps every region.
`continent`	enum	default: any allowed: any \| AF \| AN \| AS \| EU \| NA \| OC \| SA example: SA	Only return entries on this GeoNames physical continent (AF, AN, AS, EU, NA, OC, SA); any keeps every continent. Distinct from region: Cyprus is region asia but continent EU.
`search`	string	allowed: 1 – 100 example: united	Case- and diacritic-insensitive substring match against the common English name (aland finds Åland Islands).
`minArea`	float	allowed: ≥ 0 example: 1000000	Only return entries whose areaSqKm is at least this many square kilometres. The entry with no published area is excluded whenever this or maxArea is set.
`maxArea`	float	allowed: ≥ 0 example: 500	Only return entries whose areaSqKm is at most this many square kilometres. Must be ≥ minArea when both are given; the entry with no published area is excluded whenever either bound is set.
`sort`	enum	default: name allowed: name \| area-desc \| area-asc example: area-desc	Ordering of the filtered list: name is the default alphabetical order; area-desc and area-asc sort by areaSqKm, breaking ties alphabetically and placing unknown-area entries last in both directions.

region enum

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

default: any

example: region=europe

continent enum

Only return entries on this GeoNames physical continent (AF, AN, AS, EU, NA, OC, SA); any keeps every continent. Distinct from region: Cyprus is region asia but continent EU.

default: any

allowed: any | AF | AN | AS | EU | NA | OC | SA

example: continent=SA

search string

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

allowed: 1 – 100

example: search=united

minArea float

Only return entries whose areaSqKm is at least this many square kilometres. The entry with no published area is excluded whenever this or maxArea is set.

allowed: ≥ 0

example: minArea=1000000

maxArea float

Only return entries whose areaSqKm is at most this many square kilometres. Must be ≥ minArea when both are given; the entry with no published area is excluded whenever either bound is set.

allowed: ≥ 0

example: maxArea=500

sort enum

Ordering of the filtered list: name is the default alphabetical order; area-desc and area-asc sort by areaSqKm, breaking ties alphabetically and placing unknown-area entries last in both directions.

default: name

allowed: name | area-desc | area-asc

example: sort=area-desc

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: languageTags	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=languageTags

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 17

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
`areaSqKm` nullable	float	Total area in square kilometres (land plus inland water) as published by GeoNames — one rounded figure per entry, not a measurement we computed. Null where GeoNames publishes no usable figure; today that is only UM (United States Minor Outlying Islands), which it prints as 0.	43094
`continent`	string	GeoNames physical continent code: AF, AN, AS, EU, NA, OC or SA. This is a different classification from region, which is UN M49 statistical geography, and the two genuinely disagree for some entries (Cyprus is region asia but continent EU).	EU
`ccTLD`	string	Country-code top-level domain recorded by GeoNames, leading dot included. Every entry has one. The United Kingdom's is .uk, not .gb; Saint Barthélemy (BL) and Saint Martin (MF) both carry Guadeloupe's .gp because .bl and .mf have never been delegated.	.dk
`languageTags`	string[]	GeoNames' raw language column split on commas: mostly ISO 639-1 alpha-2, ISO 639-2/-3 alpha-3 (including collective codes such as cau and tut) where no alpha-2 exists, each optionally carrying an ISO 3166-1 region subtag. Not validated against the IANA Language Subtag Registry and far broader than the languages field. Empty for AQ, BV and HM.	["da-DK","en","fo","de-DK"]

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

areaSqKm float nullable

Total area in square kilometres (land plus inland water) as published by GeoNames — one rounded figure per entry, not a measurement we computed. Null where GeoNames publishes no usable figure; today that is only UM (United States Minor Outlying Islands), which it prints as 0.

example: 43094

continent string

GeoNames physical continent code: AF, AN, AS, EU, NA, OC or SA. This is a different classification from region, which is UN M49 statistical geography, and the two genuinely disagree for some entries (Cyprus is region asia but continent EU).

example: EU

ccTLD string

Country-code top-level domain recorded by GeoNames, leading dot included. Every entry has one. The United Kingdom's is .uk, not .gb; Saint Barthélemy (BL) and Saint Martin (MF) both carry Guadeloupe's .gp because .bl and .mf have never been delegated.

example: .dk

languageTags string[]

GeoNames' raw language column split on commas: mostly ISO 639-1 alpha-2, ISO 639-2/-3 alpha-3 (including collective codes such as cau and tut) where no alpha-2 exists, each optionally carrying an ISO 3166-1 region subtag. Not validated against the IANA Language Subtag Registry and far broader than the languages field. Empty for AQ, BV and HM.

example: ["da-DK","en","fo","de-DK"]

Documented examples

Build-generated requests and complete responses 7

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,
      "areaSqKm": 647500,
      "continent": "AS",
      "ccTLD": ".af",
      "languageTags": [
        "fa-AF",
        "ps",
        "uz-AF",
        "tk"
      ]
    },
    {
      "name": "Åland Islands",
      "code": "AX",
      "alpha3": "ALA",
      "numeric": "248",
      "capital": "Mariehamn",
      "region": "europe",
      "subregion": "Northern Europe",
      "currencyCode": "EUR",
    …
    "generatedAt": "2026-09-15T19:47:18.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,
      "areaSqKm": 1580,
      "continent": "EU",
      "ccTLD": ".ax",
      "languageTags": [
        "sv-AX"
      ]
    },
    {
      "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,
    …
    "generatedAt": "2026-09-15T19:47:18.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,
      "areaSqKm": 82880,
      "continent": "AS",
      "ccTLD": ".ae",
      "languageTags": [
        "ar-AE",
        "fa",
        "en",
        "hi",
        "ur"
      ]
    },
    {
      "name": "United Kingdom",
      "code": "GB",
      "alpha3": "GBR",
      "numeric": "826",
      "capital": "London",
      "region": "europe",
      "subregion": "Northern Europe",
      "currencyCode": "GBP",
      "languages": [
        "English"
    …
    "generatedAt": "2026-09-15T19:47:18.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

South America by physical continent /api/countries?continent=SA&fields=name,code,continent,region

GET /api/countries?continent=SA&fields=name,code,continent,region

{
  "data": [
    {
      "name": "Argentina",
      "code": "AR",
      "continent": "SA",
      "region": "americas"
    },
    {
      "name": "Bolivia",
      "code": "BO",
      "continent": "SA",
      "region": "americas"
    },
    {
      "name": "Brazil",
      "code": "BR",
      "continent": "SA",
      "region": "americas"
    },
    {
      "name": "Chile",
      "code": "CL",
      "continent": "SA",
      "region": "americas"
    },
    {
      "name": "Colombia",
      "code": "CO",
      "continent": "SA",
      "region": "americas"
    },
    {
      "name": "Ecuador",
      "code": "EC",
      "continent": "SA",
      "region": "americas"
    },
    {
      "name": "Falkland Islands",
    …
    "generatedAt": "2026-09-15T19:47:18.000Z"
  }
}

The ten largest countries by area /api/countries?sort=area-desc&count=10&fields=name,code,areaSqKm,continent

GET /api/countries?sort=area-desc&count=10&fields=name,code,areaSqKm,continent

{
  "data": [
    {
      "name": "Russia",
      "code": "RU",
      "areaSqKm": 17100000,
      "continent": "EU"
    },
    {
      "name": "Antarctica",
      "code": "AQ",
      "areaSqKm": 14000000,
      "continent": "AN"
    },
    {
      "name": "Canada",
      "code": "CA",
      "areaSqKm": 9984670,
      "continent": "NA"
    },
    {
      "name": "United States",
      "code": "US",
      "areaSqKm": 9629091,
      "continent": "NA"
    },
    {
      "name": "China",
      "code": "CN",
      "areaSqKm": 9596960,
      "continent": "AS"
    },
    {
      "name": "Brazil",
      "code": "BR",
      "areaSqKm": 8511965,
      "continent": "SA"
    },
    {
      "name": "Australia",
    …
    "generatedAt": "2026-09-15T19:47:18.000Z"
  }
}

European microstates under 500 km² /api/countries?continent=EU&maxArea=500&sort=area-asc&fields=name,code,areaSqKm,ccTLD

GET /api/countries?continent=EU&maxArea=500&sort=area-asc&fields=name,code,areaSqKm,ccTLD

{
  "data": [
    {
      "name": "Vatican City",
      "code": "VA",
      "areaSqKm": 0.44,
      "ccTLD": ".va"
    },
    {
      "name": "Monaco",
      "code": "MC",
      "areaSqKm": 1.95,
      "ccTLD": ".mc"
    },
    {
      "name": "Gibraltar",
      "code": "GI",
      "areaSqKm": 6.5,
      "ccTLD": ".gi"
    },
    {
      "name": "San Marino",
      "code": "SM",
      "areaSqKm": 61.2,
      "ccTLD": ".sm"
    },
    {
      "name": "Guernsey",
      "code": "GG",
      "areaSqKm": 78,
      "ccTLD": ".gg"
    },
    {
      "name": "Jersey",
      "code": "JE",
      "areaSqKm": 116,
      "ccTLD": ".je"
    },
    {
      "name": "Liechtenstein",
    …
    "generatedAt": "2026-09-15T19:47:18.000Z"
  }
}

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 · 17 fields · 4 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: languageTags	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=languageTags

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 17

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
`areaSqKm` nullable	float	Total area in square kilometres (land plus inland water) as published by GeoNames — one rounded figure per entry, not a measurement we computed. Null where GeoNames publishes no usable figure; today that is only UM (United States Minor Outlying Islands), which it prints as 0.	43094
`continent`	string	GeoNames physical continent code: AF, AN, AS, EU, NA, OC or SA. This is a different classification from region, which is UN M49 statistical geography, and the two genuinely disagree for some entries (Cyprus is region asia but continent EU).	EU
`ccTLD`	string	Country-code top-level domain recorded by GeoNames, leading dot included. Every entry has one. The United Kingdom's is .uk, not .gb; Saint Barthélemy (BL) and Saint Martin (MF) both carry Guadeloupe's .gp because .bl and .mf have never been delegated.	.dk
`languageTags`	string[]	GeoNames' raw language column split on commas: mostly ISO 639-1 alpha-2, ISO 639-2/-3 alpha-3 (including collective codes such as cau and tut) where no alpha-2 exists, each optionally carrying an ISO 3166-1 region subtag. Not validated against the IANA Language Subtag Registry and far broader than the languages field. Empty for AQ, BV and HM.	["da-DK","en","fo","de-DK"]

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

areaSqKm float nullable

example: 43094

continent string

example: EU

ccTLD string

example: .dk

languageTags string[]

example: ["da-DK","en","fo","de-DK"]

Documented examples

Build-generated requests and complete responses 4

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,
    "areaSqKm": 43094,
    "continent": "EU",
    "ccTLD": ".dk",
    "languageTags": [
      "da-DK",
      "en",
      "fo",
      "de-DK"
    ]
  },
  "meta": {
    "endpoint": "countries",
    "route": "/lookup",
    "params": {
      "code": "DK"
    },
    "generatedAt": "2026-09-15T19:47:18.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,
    "areaSqKm": 43094,
    "continent": "EU",
    "ccTLD": ".dk",
    "languageTags": [
      "da-DK",
      "en",
      "fo",
      "de-DK"
    ]
  },
  "meta": {
    "endpoint": "countries",
    "route": "/lookup",
    "params": {
      "code": "DNK"
    },
    "generatedAt": "2026-09-15T19:47:18.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-09-15T19:47:18.000Z"
  }
}

Japan's area, continent and ccTLD /api/countries/lookup?code=JP&fields=name,areaSqKm,continent,ccTLD,languageTags

GET /api/countries/lookup?code=JP&fields=name,areaSqKm,continent,ccTLD,languageTags

{
  "data": {
    "name": "Japan",
    "areaSqKm": 377835,
    "continent": "AS",
    "ccTLD": ".jp",
    "languageTags": [
      "ja"
    ]
  },
  "meta": {
    "endpoint": "countries",
    "route": "/lookup",
    "params": {
      "code": "JP"
    },
    "generatedAt": "2026-09-15T19:47:18.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.

Area, continent, ccTLD and language tags

Four columns are joined from a pinned GeoNames countryInfo.txt snapshot (CC BY 4.0), covering all 249 entries:

areaSqKm is GeoNames' total area in square kilometres — land plus inland water, one rounded published figure, not something computed here. It is null for UM (United States Minor Outlying Islands), the one entry GeoNames prints as 0; a literal zero is never returned. /api/country-stats also publishes a surfaceArea series, and it is not the same number: that one is the World Bank's FAO-sourced figure, which includes some coastal waters and excludes Greenland's ice sheet, so the two disagree by more than 5% for 28 of the 215 countries both cover — Bermuda is 53 km² here and 4,290 there, Greenland 2,166,086 against 410,450. Use this field for a stable geographic constant and that one for the World Bank's dated, revisable series.
continent is the physical grouping (AF, AN, AS, EU, NA, OC, SA) and is deliberately distinct from region, which is UN M49 statistical geography. They disagree on purpose, and not only at the edges: Cyprus is region: "asia" but continent: "EU"; M49's single americas spans NA, SA and AN (Bouvet Island and South Georgia are filed under South America statistically but are physically Antarctic); and five entries sit on continent AN where only one carries region: "antarctic". Both classifications are published unchanged rather than reconciled into one invented answer — pick the one your product actually means.
ccTLD is the country-code top-level domain with its leading dot. Three entries are not simply . + their alpha-2: the United Kingdom is .uk (not .gb), and Saint Barthélemy (BL) and Saint Martin (MF) both carry Guadeloupe's .gp, because .bl and .mf have never been delegated.
languageTags republishes GeoNames' language column in its upstream order. The only normalization is dropping the empty segment left by the stray trailing comma in Israel's row — no tag is renamed, reordered or translated. It is mostly ISO 639-1 alpha-2, falls back to ISO 639-2/-3 alpha-3 where no alpha-2 exists (including collective codes such as cau and tut), and may carry an ISO 3166-1 region subtag (en-GB). It is not validated against the IANA Language Subtag Registry and is not the same list as languages: India carries 26 tags here — the broadest row in the column — against two languages labels, and Russia 23 against one. It is empty for the three entries GeoNames records no language for (AQ, BV, HM).

Two countryInfo.txt columns are deliberately left out. Population is not published here at all: the upstream column is stale and of mixed vintage (Afghanistan still carries its 2018 figure) and carries no observation year, and a population without the year it was observed is a number you cannot check. The postal-code regex column is rejected on accuracy grounds — 31 of its rows contradict their own mask — and /api/postal-code-formats derives every published pattern from the mask instead.

Filtering and ordering

The list route is alphabetical by default, and region, continent and search each genuinely restrict every returned record and compose with one another. minArea/maxArea bound areaSqKm in square kilometres; because an entry with an unknown area cannot be proven to satisfy a bound, the one null-area entry is excluded whenever either bound is set, and the response says so in meta.warnings. A minArea above maxArea is a 400 naming both values. sort accepts name (the default alphabetical order), area-desc and area-asc; area sorts break ties in alphabetical order and put unknown-area entries last in both directions. count limits the already-filtered, already-sorted list, so ?sort=area-desc&count=10 is the ten largest.

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
Rank or bucket countries by total area, or restrict a list to one physical continent
Map an ISO country code to its ccTLD for domain, email or geo-routing validation

Frequently asked questions

Practical answers about this endpoint 6

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.

How do I filter the country list by region or by name?

Use region=africa|americas|asia|europe|oceania|antarctic for UN M49 geography, and search= for a case- and diacritic-insensitive match on the common English name. They compose with the continent and area filters, and count limits the already-filtered list.

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.

What is the difference between region and continent here?

region is UN M49 statistical geography; continent is the GeoNames physical code (AF, AN, AS, EU, NA, OC, SA). They disagree on purpose — Cyprus is region: asia but continent: EU, and M49's single americas spans NA, SA and AN. Both filters work independently and compose.

Can I sort or filter countries by area?

Yes — minArea and maxArea bound areaSqKm in square kilometres and sort=area-desc or sort=area-asc orders the result, so ?sort=area-desc&count=10 is the ten largest. Areas are GeoNames figures; the one entry with no published area returns null and is excluded whenever an area bound is set.

Standards & references

Primary sources behind the contract

Useful next tools in the catalog

World Cities API REAL DATA

31,000+ world cities from a pinned GeoNames snapshot: coordinates, IANA timezone, elevation, population and capital flag — filter, search or rank by distance.

Country Statistics API REAL DATA

Population, GDP, life expectancy and five more World Bank indicators for 215 countries, 1960–2025: latest value, one year, a full annual series or a ranking.

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 (filter by region, continent, area or 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

Area, continent, ccTLD and language tags

Filtering and ordering

Use it for

Frequently asked questions

Standards & references

Related APIs