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.