Access a complete, standards-compliant dataset of countries, territories, and their subdivisions. Supports alpha-2, alpha-3, and numeric codes with UN M.49 geographic classification.
Complete ISO 3166-1 (countries) and ISO 3166-2 (subdivisions) datasets including states, provinces, regions, departments, and more.
Look up countries by alpha-2 (US), alpha-3 (USA), or numeric (840)
codes. All three formats are accepted interchangeably.
Filter countries by UN M.49 region, sub-region, and intermediate region for geographic analysis and reporting.
Validate multiple country or subdivision codes in a single request. Get detailed results with matching country names and error details.
# Look up a country with its subdivisions
$ curl https://api.apicrate.io/api/v1/countries/US \
-H "X-API-Key: YOUR_API_KEY"
# Response (truncated)
{
"status": "ok",
"data": {
"name": "United States of America",
"alpha_2": "US",
"alpha_3": "USA",
"numeric": "840",
"region": "Americas",
"sub_region": "Northern America",
"subdivisions": [
{"code": "US-CA", "name": "California", "type": "state"},
{"code": "US-NY", "name": "New York", "type": "state"}
]
}
}
import requests
# Search countries by region
response = requests.get(
"https://api.apicrate.io/api/v1/countries",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"region": "Europe", "fields": "name,alpha_2"},
)
for country in response.json()["data"]:
print(f"{country['alpha_2']}: {country['name']}")
// Validate a batch of country codes
const res = await fetch("https://api.apicrate.io/api/v1/countries/validate", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ codes: ["US", "GB", "XX", "DE"] }),
});
const { data } = await res.json();
// data.results: [{code: "US", valid: true, name: "United States"}, ...]
/api/v1/countries
List countries
/api/v1/countries/{code}
Get a country by code
/api/v1/countries/{code}/subdivisions
List subdivisions of a country
/api/v1/subdivisions/{code}
Get a subdivision by code
/api/v1/countries/validate
Validate country codes (batch)
/api/v1/subdivisions/validate
Validate subdivision codes (batch)
The dataset includes all 249 ISO 3166-1 countries and territories, with over 5,000 ISO 3166-2 subdivisions.
Yes. Use the q query parameter on the /api/v1/countries endpoint to
perform free-text search across country names.
The API covers all ISO 3166-2 subdivision types including states, provinces, regions, departments, districts, parishes, and more.
The definitions database is updated regularly. Check the X-Definitions-Updated
response header for the latest update date.
Create a free account and start making requests in under a minute.