Countries

ISO 3166-1 country and subdivision lookup.

GET /api/v1/countries

List or search countries.

Parameters

Name	In	Required	Description
region	query	no	Filter by region (e.g. Europe, Asia)
sub_region	query	no	Filter by sub-region (e.g. Northern Europe)
q	query	no	Free-text search across country names
limit	query	no	Maximum results to return (default 50)
offset	query	no	Number of results to skip
fields	query	no	Comma-separated list of response fields to include

Example

curl -H "X-API-Key: $KEY" \
  "https://api.apicrate.io/api/v1/countries?region=Europe&limit=2"

{
  "count": 44,
  "results": [
    {
      "alpha2": "DE",
      "alpha3": "DEU",
      "numeric": "276",
      "name": "Germany",
      "official_name": "Federal Republic of Germany",
      "region": "Europe",
      "sub_region": "Western Europe",
      "capital": "Berlin"
    },
    {
      "alpha2": "FR",
      "alpha3": "FRA",
      "numeric": "250",
      "name": "France",
      "official_name": "French Republic",
      "region": "Europe",
      "sub_region": "Western Europe",
      "capital": "Paris"
    }
  ]
}

GET /api/v1/countries/{code}

Get a single country by alpha-2, alpha-3, or numeric code.

Parameters

Name	In	Required	Description
code	path	yes	Country code (alpha-2, alpha-3, or numeric)
fields	query	no	Comma-separated list of response fields to include

Example

curl -H "X-API-Key: $KEY" \
  https://api.apicrate.io/api/v1/countries/US

{
  "alpha2": "US",
  "alpha3": "USA",
  "numeric": "840",
  "name": "United States of America",
  "official_name": "United States of America",
  "region": "Americas",
  "sub_region": "Northern America",
  "capital": "Washington, D.C.",
  "languages": ["en"],
  "currencies": ["USD"],
  "calling_codes": ["+1"]
}

GET /api/v1/countries/{code}/subdivisions

List subdivisions (states, provinces, regions) for a country.

Parameters

Name	In	Required	Description
code	path	yes	Country code (alpha-2)
type	query	no	Filter by subdivision type (e.g. state, province)
q	query	no	Free-text search across subdivision names
limit	query	no	Maximum results to return (default 50)
offset	query	no	Number of results to skip

Example

curl -H "X-API-Key: $KEY" \
  "https://api.apicrate.io/api/v1/countries/US/subdivisions?type=state&limit=2"

{
  "count": 50,
  "results": [
    {"code": "US-CA", "name": "California", "type": "state"},
    {"code": "US-TX", "name": "Texas", "type": "state"}
  ]
}

GET /api/v1/subdivisions/{code}

Get a single subdivision by its ISO 3166-2 code.

Parameters

Name	In	Required	Description
code	path	yes	ISO 3166-2 subdivision code (e.g. US-CA)

Example

curl -H "X-API-Key: $KEY" \
  https://api.apicrate.io/api/v1/subdivisions/US-CA

{
  "code": "US-CA",
  "name": "California",
  "type": "state",
  "country": "US",
  "parent": null
}

POST /api/v1/countries/validate

Validate a batch of country codes.

Parameters

Name	In	Required	Description
codes	body	yes	Array of country codes to validate

Example

curl -X POST https://api.apicrate.io/api/v1/countries/validate \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["US", "XX", "DE"]}'

{
  "results": [
    {"code": "US", "valid": true, "name": "United States of America"},
    {"code": "XX", "valid": false, "name": null},
    {"code": "DE", "valid": true, "name": "Germany"}
  ]
}

POST /api/v1/subdivisions/validate

Validate a batch of subdivision codes.

Parameters

Name	In	Required	Description
codes	body	yes	Array of ISO 3166-2 subdivision codes to validate

Example

curl -X POST https://api.apicrate.io/api/v1/subdivisions/validate \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["US-CA", "US-ZZ", "DE-BY"]}'

{
  "results": [
    {"code": "US-CA", "valid": true, "name": "California"},
    {"code": "US-ZZ", "valid": false, "name": null},
    {"code": "DE-BY", "valid": true, "name": "Bavaria"}
  ]
}