ISO 3166-2 subdivisions API

Return a country's first-level ISO 3166-2 subdivisions (states/provinces/regions) with their codes, names, and subdivision type, or resolve a single subdivision — the value-add being the inline subdivision table. Differs from ref/country-codes which is country-level only. Answers 'list the states of the US', 'what is CA-QC', 'provinces of Canada', 'ISO code for Bavaria'.

Price$0.01per request

MethodPOST

Route/v1/ref/iso-3166-2

StatusLive

MIME typeapplication/json

Rate limit60/minute

CacheNo cache

refisoiso3166subdivisionstateprovinceregioncountry

API URLhttps://x402.hexl.dev/v1/ref/iso-3166-2

Integration docs

Example request

{
  "country": "CA",
  "subdivision": "QC"
}

Example response

{
  "country": "CA",
  "countryName": "Canada",
  "found": true,
  "subdivision": {
    "code": "QC",
    "name": "Quebec",
    "type": "province",
    "isoCode": "CA-QC"
  }
}

Input schema

{
  "type": "object",
  "required": [
    "country"
  ],
  "properties": {
    "country": {
      "type": "string",
      "examples": [
        "US"
      ]
    },
    "subdivision": {
      "type": "string",
      "examples": [
        "CA"
      ]
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}