Skip to main content
GET
/
v1
/
iso
/
country
/
convert
curl -X GET 'https://api.countrystatecity.in/v1/iso/country/convert?from=iso2&to=iso3&value=US' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

{
  "from": "iso2",
  "to": "iso3",
  "input": "US",
  "result": "USA"
}

Documentation Index

Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt

Use this file to discover all available pages before exploring further.

Convert a country code between the three ISO 3166-1 formats in a single call:
  • alpha-2 ↔ alpha-3 (e.g. US ↔ USA)
  • alpha-2 ↔ numeric (e.g. US ↔ 840)
  • alpha-3 ↔ numeric (e.g. USA ↔ 840)
Useful when an upstream system gives you one format and a downstream service expects another.
Availability: Starter plan and above. Returns 403 on Community plan.
Cache reuse: Conversions share the same cache slot as /v1/iso/country. A previous ?iso2=US lookup serves any ?from=iso2&value=US&to=... conversion without a fresh database hit. The target column is extracted after the cache read, so different to values reuse the same slot.Numeric inputs 4 and 004 resolve to the same cache slot.

​
Authentication

​
X-CSCAPI-KEY
string
required
Your API key for authentication

​
Query Parameters

​
from
string
required
Source format. One of iso2, iso3, numeric.
​
to
string
required
Target format. One of iso2, iso3, numeric. Must differ from from.
​
value
string
required
The code to convert. Must match the format named in from:
  • from=iso2 → 2 letters (e.g. US)
  • from=iso3 → 3 letters (e.g. USA)
  • from=numeric → 1–3 digits, non-zero (e.g. 840 or 4)
Letter codes are auto-uppercased.

​
Response

​
from
string
Echo of the source format you requested.
​
to
string
Echo of the target format you requested.
​
input
string
Echo of the value you sent — useful for matching responses to requests when batching.
​
result
string
The converted code. For to=numeric, returned zero-padded to 3 digits (e.g. "840").
curl -X GET 'https://api.countrystatecity.in/v1/iso/country/convert?from=iso2&to=iso3&value=US' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

{
  "from": "iso2",
  "to": "iso3",
  "input": "US",
  "result": "USA"
}