Global Data API · v1

Reference data for applications that cross borders.

Countries, subdivisions, phone formats, postal code rules and address examples. Everything an international checkout form needs, in one consistent shape, with the ISO codes you already index on.

Start free Browse the reference

Countries: 249
Free tier: 25K req
Cached: 24h

🇧🇷Brazil+55 · 27 statesBR
🇯🇵Japan+81 · 47 prefecturesJP
🇩🇪Germany+49 · 16 statesDE
🇨🇦Canada+1 · 13 provincesCA

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"];

The datasets

Five datasets, one key

Each dataset is a separate endpoint family but shares the same authentication, quota and error contract.

Countries

Names, official names, translations, calling codes, regions and flags.

Phone

Calling codes, formatted examples and validation patterns for phone inputs.

/v1/phone/{country_code}

Postal codes

Regex patterns, display formats and valid examples per country.

/v1/postal-code/{country_code}

Subdivisions

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

Addresses

Correctly ordered address examples, ready to use as form placeholders.

/v1/address-example/{country_code}

Where it fits

Positioned as infrastructure

This is not a country list. It is the reference layer that keeps forms, validation and storage consistent across every market you sell in.

International checkout: Drive the country select, then swap the subdivision list, postal code mask and phone format to match the selection.
Address validation: Validate postal codes against the country pattern before a shipment is created instead of after it fails.
Onboarding and CRM: Store ISO codes rather than free text, and render localised names from translations at display time.
Localisation: Serve country and subdivision names in Portuguese, Spanish, French or German from the same records.

Driving a checkout form

// 1. Country select
const { countries } = await client.get("/v1/countries?locale=pt");

// 2. Subdivision select for the chosen country
const { subdivisions } = await client.get("/v1/subdivisions/BR?locale=pt");

// 3. Postal code mask and validation
const { postal_code } = await client.get("/v1/postal-code/BR");
const isValid = new RegExp(postal_code.pattern).test(input);

// 4. Phone placeholder and mask
const { example, calling_code } = await client.get("/v1/phone/BR");
input.placeholder = example.national;

Country, subdivision and metadata responses are cacheable for up to 24 hours, which is why this product carries the highest quotas on the platform.

Stop maintaining your own country table.

25,000 requests a month on the free plan, no payment method required, and responses you can cache for a day.

Create account Compare plans