Documentation

Endpoint reference

All five dataset families, their parameters and responses.

Countries

GET/v1/countries

List countries

Every country in the dataset. Returns the compact shape by default, or the full record with translations when view=full.

Parameter	In	Required	Description
locale	query	no	Language for translated names. Falls back to English.
view	query	no	Use full to include translations, calling code and region.

curl "https://api.countrykit-api.com/v1/countries" \
  -H "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"

const response = await fetch("https://api.countrykit-api.com/v1/countries", {
  headers: { Authorization: "Bearer data_live_xxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.countrykit-api.com/v1/countries",
    headers={"Authorization": "Bearer data_live_xxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.countrykit-api.com/v1/countries", false, $context), true);

200 OK

{
  "count": 249,
  "locale": "en",
  "countries": [
    {
      "code": "BR",
      "name": "Brazil",
      "official_name": "Federative Republic of Brazil",
      "flag": { "emoji": "🇧🇷" }
    }
  ]
}

GET/v1/countries/{country_code}

Get one country

The full record for a single country, including translations, calling code, region and flag.

Parameter	In	Required	Description
country_code	path	yes	ISO 3166-1 alpha-2 country code.
locale	query	no	Language for translated names. Falls back to English.

curl "https://api.countrykit-api.com/v1/countries/BR" \
  -H "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"

const response = await fetch("https://api.countrykit-api.com/v1/countries/BR", {
  headers: { Authorization: "Bearer data_live_xxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.countrykit-api.com/v1/countries/BR",
    headers={"Authorization": "Bearer data_live_xxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.countrykit-api.com/v1/countries/BR", false, $context), true);

200 OK

{
  "code": "BR",
  "name": { "common": "Brazil", "official": "Federative Republic of Brazil" },
  "translations": {
    "pt": "Brasil",
    "en": "Brazil",
    "es": "Brasil",
    "fr": "Brésil",
    "de": "Brasilien"
  },
  "calling_code": "+55",
  "region": "South America",
  "flag": { "emoji": "🇧🇷" }
}

Phone

GET/v1/phone/{country_code}

Phone number metadata

Calling code, formatted examples and validation patterns. Everything a phone input needs to mask and validate a number.

Parameter	In	Required	Description
country_code	path	yes	ISO 3166-1 alpha-2 country code.

curl "https://api.countrykit-api.com/v1/phone/BR" \
  -H "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"

const response = await fetch("https://api.countrykit-api.com/v1/phone/BR", {
  headers: { Authorization: "Bearer data_live_xxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.countrykit-api.com/v1/phone/BR",
    headers={"Authorization": "Bearer data_live_xxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.countrykit-api.com/v1/phone/BR", false, $context), true);

200 OK

{
  "country": "BR",
  "calling_code": "+55",
  "example": {
    "e164": "+5511999999999",
    "international": "+55 11 99999-9999",
    "national": "(11) 99999-9999"
  },
  "patterns": {
    "national": "(\\d{2}) \\d{5}-\\d{4}",
    "possible_lengths": [10, 11]
  }
}

Postal codes

GET/v1/postal-code/{country_code}

Postal code metadata

The validation pattern, display format and a valid example for a country's postal codes.

Parameter	In	Required	Description
country_code	path	yes	ISO 3166-1 alpha-2 country code.

curl "https://api.countrykit-api.com/v1/postal-code/BR" \
  -H "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"

const response = await fetch("https://api.countrykit-api.com/v1/postal-code/BR", {
  headers: { Authorization: "Bearer data_live_xxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.countrykit-api.com/v1/postal-code/BR",
    headers={"Authorization": "Bearer data_live_xxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.countrykit-api.com/v1/postal-code/BR", false, $context), true);

200 OK

{
  "country": "BR",
  "postal_code": {
    "pattern": "\\d{8}",
    "format": "01001-000",
    "example": "01001-000"
  }
}

Subdivisions

GET/v1/subdivisions/{country_code}

List subdivisions

States, provinces or regions with their ISO 3166-2 codes and administrative type.

Parameter	In	Required	Description
country_code	path	yes	ISO 3166-1 alpha-2 country code.
locale	query	no	Language for translated names. Falls back to English.

curl "https://api.countrykit-api.com/v1/subdivisions/BR" \
  -H "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"

const response = await fetch("https://api.countrykit-api.com/v1/subdivisions/BR", {
  headers: { Authorization: "Bearer data_live_xxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.countrykit-api.com/v1/subdivisions/BR",
    headers={"Authorization": "Bearer data_live_xxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.countrykit-api.com/v1/subdivisions/BR", false, $context), true);

200 OK

{
  "country": "BR",
  "subdivisions": [
    { "code": "BR-SP", "name": "São Paulo", "type": "State" },
    { "code": "BR-DF", "name": "Distrito Federal", "type": "Federal District" }
  ]
}

GET/v1/subdivisions/{country_code}/{subdivision_code}

Get one subdivision

A single subdivision resolved by its ISO 3166-2 code.

Parameter	In	Required	Description
country_code	path	yes	ISO 3166-1 alpha-2 country code.
subdivision_code	path	yes	ISO 3166-2 subdivision code, including the country prefix.
locale	query	no	Language for translated names. Falls back to English.

curl "https://api.countrykit-api.com/v1/subdivisions/BR/BR-SP" \
  -H "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"

const response = await fetch("https://api.countrykit-api.com/v1/subdivisions/BR/BR-SP", {
  headers: { Authorization: "Bearer data_live_xxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.countrykit-api.com/v1/subdivisions/BR/BR-SP",
    headers={"Authorization": "Bearer data_live_xxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.countrykit-api.com/v1/subdivisions/BR/BR-SP", false, $context), true);

200 OK

{
  "code": "BR-SP",
  "name": "São Paulo",
  "type": "State"
}

Addresses

GET/v1/address-example/{country_code}

Address example

A realistic, correctly ordered address for a country. Useful as placeholder text in checkout forms.

Parameter	In	Required	Description
country_code	path	yes	ISO 3166-1 alpha-2 country code.

curl "https://api.countrykit-api.com/v1/address-example/BR" \
  -H "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"

const response = await fetch("https://api.countrykit-api.com/v1/address-example/BR", {
  headers: { Authorization: "Bearer data_live_xxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.countrykit-api.com/v1/address-example/BR",
    headers={"Authorization": "Bearer data_live_xxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer data_live_xxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.countrykit-api.com/v1/address-example/BR", false, $context), true);

200 OK

{
  "country": "BR",
  "example": {
    "street": "Avenida Paulista, 1578",
    "city": "São Paulo",
    "subdivision": "SP",
    "postal_code": "01310-200"
  }
}