countries

Country reference lookups

List all countries

GET

https://api.apicodex.io/countries

/v1/all

Returns every country (enriched). Optionally filter by region, project a comma-separated subset of fields, and cap results with limit (default 300).

List all countries › query Parameters

fields

string

Comma-separated field names to project (e.g. name_common,cca2,calling_codes).

Example: name_common,cca2,calling_codes

region

string · enum

Filter by region (case-insensitive).

Enum values:

Africa

Americas

Asia

Europe

Oceania

Antarctic

Example: Oceania

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List all countries › Responses

A list of countries

CountryList

count

integer · required

Number of countries returned in this response.

Example: 2

total

integer · required

Total number of countries matching before limit.

Example: 27

Country[] · required

Resolve a single country by code

GET

https://api.apicodex.io/countries

/v1/code/{code}

Resolve one country by cca2, cca3, ccn3 or cioc, tried in that order, case-insensitive.

Resolve a single country by code › path Parameters

code

string · required

A cca2, cca3, ccn3 or cioc code (e.g. AW, ABW, 533, ARU).

Example: AW

Resolve a single country by code › Responses

The matched country

Country · required

A country enriched with flag URLs and normalized calling codes.

GET/v1/code/{code}

curl 'https://api.apicodex.io/countries/v1/code/:code?apikey=<api-key>'

Example Responses

{
  "country": {
    "name_common": "Aruba",
    "name_official": "Aruba",
    "cca2": "AW",
    "cca3": "ABW",
    "ccn3": "533",
    "cioc": "ARU",
    "region": "Americas",
    "subregion": "Caribbean",
    "capital": [
      "Oranjestad"
    ],
    "currencies": {
      "AWG": {
        "name": "Aruban florin",
        "symbol": "ƒ"
      }
    },
    "idd": {
      "root": "+2",
      "suffixes": [
        "97"
      ]
    },
    "languages": {
      "nld": "Dutch",
      "pap": "Papiamento"
    },
    "latlng": [
      12.5,
      -69.97
    ],
    "area": 180,
    "borders": [],
    "tld": [
      ".aw"
    ],
    "flag_emoji": "🇦🇼",
    "demonyms": {
      "f": "Aruban",
      "m": "Aruban"
    },
    "landlocked": false,
    "independent": false,
    "unMember": false,
    "altSpellings": [
      "AW"
    ],
    "flag_png": "https://flagcdn.com/w320/aw.png",
    "flag_svg": "https://flagcdn.com/aw.svg",
    "calling_codes": [
      "+297"
    ]
  }
}

json

application/json

Search countries by name

GET

https://api.apicodex.io/countries

/v1/search

Partial, case-insensitive search over name_common, name_official and altSpellings. Results are ranked exact > prefix > substring.

Search countries by name › query Parameters

name

string · required

Name substring to search for.

Example: united

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 50

Search countries by name › Responses

Ranked search results

query

string

count

integer

total

integer

Country[]

List countries in a region

GET

https://api.apicodex.io/countries

/v1/region/{region}

List countries in a region › path Parameters

region

string · enum · required

Region name (case-insensitive).

Enum values:

Africa

Americas

Asia

Europe

Oceania

Antarctic

Example: Europe

List countries in a region › query Parameters

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List countries in a region › Responses

Countries in the region

region

string

count

integer

total

integer

Country[]

List countries using a currency

GET

https://api.apicodex.io/countries

/v1/currency/{code}

List countries using a currency › path Parameters

code

string · required

ISO 4217 currency code (case-insensitive).

Example: EUR

List countries using a currency › query Parameters

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List countries using a currency › Responses

Countries using the currency

currency

string

count

integer

total

integer

Country[]

List countries with a language

GET

https://api.apicodex.io/countries

/v1/language/{code}

List countries with a language › path Parameters

code

string · required

ISO 639-3 language code (case-insensitive).

Example: eng

List countries with a language › query Parameters

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List countries with a language › Responses

Countries speaking the language

language

string

count

integer

total

integer

Country[]

List countries by international calling code

GET

https://api.apicodex.io/countries

/v1/calling-code/{code}

Matches an international calling code with or without a leading '+'. Tries an exact full-code match then the dialing root, so shared roots (+1 -> US, CA) and specific codes (+297 -> Aruba) both resolve.

List countries by international calling code › path Parameters

code

string · required

Calling code digits, optional leading '+' (e.g. +44, 1, 297).

Example: 1

List countries by international calling code › query Parameters

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List countries by international calling code › Responses

Countries matching the calling code

calling_code

string

count

integer

total

integer

Country[]

Countries API

countries

Country reference lookups

List all countries

GET

https://api.apicodex.io/countries

/v1/all

Returns every country (enriched). Optionally filter by region, project a comma-separated subset of fields, and cap results with limit (default 300).

List all countries › query Parameters

fields

string

Comma-separated field names to project (e.g. name_common,cca2,calling_codes).

Example: name_common,cca2,calling_codes

region

string · enum

Filter by region (case-insensitive).

Enum values:

Africa

Americas

Asia

Europe

Oceania

Antarctic

Example: Oceania

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List all countries › Responses

A list of countries

CountryList

count

integer · required

Number of countries returned in this response.

Example: 2

total

integer · required

Total number of countries matching before limit.

Example: 27

Country[] · required

Resolve a single country by code

GET

https://api.apicodex.io/countries

/v1/code/{code}

Resolve one country by cca2, cca3, ccn3 or cioc, tried in that order, case-insensitive.

Resolve a single country by code › path Parameters

code

string · required

A cca2, cca3, ccn3 or cioc code (e.g. AW, ABW, 533, ARU).

Example: AW

Resolve a single country by code › Responses

The matched country

Country · required

A country enriched with flag URLs and normalized calling codes.

GET/v1/code/{code}

curl 'https://api.apicodex.io/countries/v1/code/:code?apikey=<api-key>'

Example Responses

{
  "country": {
    "name_common": "Aruba",
    "name_official": "Aruba",
    "cca2": "AW",
    "cca3": "ABW",
    "ccn3": "533",
    "cioc": "ARU",
    "region": "Americas",
    "subregion": "Caribbean",
    "capital": [
      "Oranjestad"
    ],
    "currencies": {
      "AWG": {
        "name": "Aruban florin",
        "symbol": "ƒ"
      }
    },
    "idd": {
      "root": "+2",
      "suffixes": [
        "97"
      ]
    },
    "languages": {
      "nld": "Dutch",
      "pap": "Papiamento"
    },
    "latlng": [
      12.5,
      -69.97
    ],
    "area": 180,
    "borders": [],
    "tld": [
      ".aw"
    ],
    "flag_emoji": "🇦🇼",
    "demonyms": {
      "f": "Aruban",
      "m": "Aruban"
    },
    "landlocked": false,
    "independent": false,
    "unMember": false,
    "altSpellings": [
      "AW"
    ],
    "flag_png": "https://flagcdn.com/w320/aw.png",
    "flag_svg": "https://flagcdn.com/aw.svg",
    "calling_codes": [
      "+297"
    ]
  }
}

json

application/json

Search countries by name

GET

https://api.apicodex.io/countries

/v1/search

Partial, case-insensitive search over name_common, name_official and altSpellings. Results are ranked exact > prefix > substring.

Search countries by name › query Parameters

name

string · required

Name substring to search for.

Example: united

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 50

Search countries by name › Responses

Ranked search results

query

string

count

integer

total

integer

Country[]

List countries in a region

GET

https://api.apicodex.io/countries

/v1/region/{region}

List countries in a region › path Parameters

region

string · enum · required

Region name (case-insensitive).

Enum values:

Africa

Americas

Asia

Europe

Oceania

Antarctic

Example: Europe

List countries in a region › query Parameters

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List countries in a region › Responses

Countries in the region

region

string

count

integer

total

integer

Country[]

List countries using a currency

GET

https://api.apicodex.io/countries

/v1/currency/{code}

List countries using a currency › path Parameters

code

string · required

ISO 4217 currency code (case-insensitive).

Example: EUR

List countries using a currency › query Parameters

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List countries using a currency › Responses

Countries using the currency

currency

string

count

integer

total

integer

Country[]

List countries with a language

GET

https://api.apicodex.io/countries

/v1/language/{code}

List countries with a language › path Parameters

code

string · required

ISO 639-3 language code (case-insensitive).

Example: eng

List countries with a language › query Parameters

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List countries with a language › Responses

Countries speaking the language

language

string

count

integer

total

integer

Country[]

List countries by international calling code

GET

https://api.apicodex.io/countries

/v1/calling-code/{code}

List countries by international calling code › path Parameters

code

string · required

Calling code digits, optional leading '+' (e.g. +44, 1, 297).

Example: 1

List countries by international calling code › query Parameters

limit

integer · min: 1 · max: 500

Max results, clamped 1..500.

Default: 300

List countries by international calling code › Responses

Countries matching the calling code

calling_code

string

count

integer

total

integer

Country[]