Documentation

Getting started

From an empty account to a country record in four steps.

The shape of the API

Five dataset families live under one product: countries, subdivisions, phone metadata, postal code rules and address examples. All of them are versioned under /v1, authenticated with the same bearer token, and share one error envelope.

Because the data is reference material rather than live state, responses carry generous cache headers. Countries are cacheable for an hour, metadata for a day.

Four steps

Create an account. The free plan activates immediately, with no payment method.
Subscribe to the Global Data product from the billing page.
Create an API key. The full secret is displayed once, so store it right away.
Send the key as a bearer token on any /v1 request.

Your first request

cURL

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

Country codes

Every path parameter that identifies a country expects an ISO 3166-1 alpha-2 code, case-insensitive. Subdivisions use the full ISO 3166-2 code including the country prefix, such as BR-SP.

In your language

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" },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(error.message);
}

const country = await response.json();
console.log(country.calling_code, country.translations.pt);

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

const { subdivisions } = await response.json();

for (const subdivision of subdivisions) {
  console.log(subdivision.code, subdivision.name);
}

import requests

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

phone = response.json()
print(phone["calling_code"], phone["example"]["national"])

<?php

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

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

echo $postal["postal_code"]["format"];