Convert ISO Code

Translate a country code between ISO 3166-1 alpha-2, alpha-3, and numeric formats

GET /v1/iso/country/convert

cURL (alpha-2 → alpha-3)

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

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

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

const params = new URLSearchParams({ from: 'iso2', to: 'iso3', value: 'DE' });
const response = await fetch(
  `https://api.countrystatecity.in/v1/iso/country/convert?${params}`,
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const { result } = await response.json();
console.log(result); // "DEU"

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/iso/country/convert',
  params={'from': 'iso2', 'to': 'numeric', 'value': 'JP'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

print(response.json()['result'])  # "392"

200 - Success (alpha-2 → alpha-3)

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

{
  "from": "iso3",
  "to": "numeric",
  "input": "IND",
  "result": "356"
}

{
  "error": "Invalid query parameters: from and to must be different"
}

{
  "error": "Invalid query parameters: value does not match the format required by from"
}

{
  "error": "Invalid query parameters: from: must be one of: iso2, iso3, numeric"
}

{
  "error": "This feature is not available on your current plan.",
  "feature": "isoLookup",
  "upgradeUrl": "https://app.countrystatecity.in/pricing"
}

{
  "error": "Country not found for the given code"
}

{
  "error": "No iso3 code available for this country"
}

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 (alpha-2 → alpha-3)

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

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

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

const params = new URLSearchParams({ from: 'iso2', to: 'iso3', value: 'DE' });
const response = await fetch(
  `https://api.countrystatecity.in/v1/iso/country/convert?${params}`,
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const { result } = await response.json();
console.log(result); // "DEU"

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/iso/country/convert',
  params={'from': 'iso2', 'to': 'numeric', 'value': 'JP'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

print(response.json()['result'])  # "392"

200 - Success (alpha-2 → alpha-3)

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

{
  "from": "iso3",
  "to": "numeric",
  "input": "IND",
  "result": "356"
}

{
  "error": "Invalid query parameters: from and to must be different"
}

{
  "error": "Invalid query parameters: value does not match the format required by from"
}

{
  "error": "Invalid query parameters: from: must be one of: iso2, iso3, numeric"
}

{
  "error": "This feature is not available on your current plan.",
  "feature": "isoLookup",
  "upgradeUrl": "https://app.countrystatecity.in/pricing"
}

{
  "error": "Country not found for the given code"
}

{
  "error": "No iso3 code available for this country"
}

Related Endpoints

• Lookup Country by ISO Code — return the full country record instead of just the converted code
• Lookup State by ISO Code — ISO 3166-2 subdivision lookup