ISO 3166 country code cross-walk API

Given an alpha-2, alpha-3, numeric code, or country name, return the full ISO 3166-1 cross-walk (alpha2/alpha3/numeric/name) plus UN M49 region/subregion and a validity flag — the normalization agents need for messy country fields. Answers 'convert US to alpha-3', 'what is country code 826', 'is XX a valid country', 'region for Japan'.

Price$0.01per request

MethodPOST

Route/v1/ref/country-codes

StatusLive

MIME typeapplication/json

Rate limit60/minute

CacheNo cache

refcountry-codesiso-3166alpha2alpha3countryregiongeo

API URLhttps://x402.hexl.dev/v1/ref/country-codes

Integration docs

Example request

{
  "query": "US"
}

Example response

{
  "query": "US",
  "valid": true,
  "name": "United States",
  "alpha2": "US",
  "alpha3": "USA",
  "numeric": "840",
  "region": "Americas",
  "subregion": "Northern America"
}

Input schema

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "examples": [
        "US",
        "DEU",
        "826",
        "Japan"
      ]
    }
  }
}

Output schema

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