Lookup Country by ISO Code

Find a country by ISO 3166-1 alpha-2, alpha-3, or numeric code

GET /v1/iso/country

cURL (alpha-2)

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

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

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

const response = await fetch(
  'https://api.countrystatecity.in/v1/iso/country?iso2=US',
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const country = await response.json();
console.log(`${country.name} (id ${country.id})`);

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/iso/country',
  params={'iso3': 'USA'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

country = response.json()
print(f"{country['name']} → numeric {country['numeric_code']}")

200 - Success

{
  "id": 233,
  "name": "United States",
  "iso2": "US",
  "iso3": "USA",
  "numeric_code": "840"
}

{
  "error": "Invalid query parameters: Provide exactly one of: iso2, iso3, numeric"
}

{
  "error": "Invalid query parameters: iso2: must be a 2-letter code"
}

{
  "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"
}

Look up a single country by any one of the three ISO 3166-1 codes: 2-letter (alpha-2), 3-letter (alpha-3), or 3-digit numeric. Exactly one query parameter must be provided.

This is the canonical lookup when you have an ISO code from an external system (payment gateway, geolocation service, address parser) and need to resolve it to the country record.

Availability: Starter plan and above. Returns 403 on Community plan.

Responses are cached server-side for 1 hour. The cache slot is shared with /v1/iso/country/convert — warming the cache via one endpoint serves the other for free. Numeric codes 4 and 004 resolve to the same cache slot.

Authentication

X-CSCAPI-KEY · string · required

Your API key for authentication

Query Parameters

Provide exactly one of the three. Sending two or zero returns 400.

iso2 · string

ISO 3166-1 alpha-2 code, e.g. US, IN, DE. Case-insensitive (auto-uppercased).

iso3 · string

ISO 3166-1 alpha-3 code, e.g. USA, IND, DEU. Case-insensitive.

numeric · string

ISO 3166-1 numeric code, 1–3 digits. Accepts padded (004) and unpadded (4) forms. All-zero values are rejected.

Response

id · integer

Internal CSC country ID — same value used by /v1/countries/:id and other foreign-key references.

name · string

Official country name in English.

iso2 · string

ISO 3166-1 alpha-2 code (e.g. "US").

iso3 · string

ISO 3166-1 alpha-3 code (e.g. "USA").

numeric_code · string | null

ISO 3166-1 numeric code, zero-padded to 3 digits (e.g. "840"). null for entries without an assigned numeric code.

cURL (alpha-2)

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

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

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

const response = await fetch(
  'https://api.countrystatecity.in/v1/iso/country?iso2=US',
  { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);

const country = await response.json();
console.log(`${country.name} (id ${country.id})`);

import requests

response = requests.get(
  'https://api.countrystatecity.in/v1/iso/country',
  params={'iso3': 'USA'},
  headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)

country = response.json()
print(f"{country['name']} → numeric {country['numeric_code']}")

200 - Success

{
  "id": 233,
  "name": "United States",
  "iso2": "US",
  "iso3": "USA",
  "numeric_code": "840"
}

{
  "error": "Invalid query parameters: Provide exactly one of: iso2, iso3, numeric"
}

{
  "error": "Invalid query parameters: iso2: must be a 2-letter code"
}

{
  "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"
}

Related Endpoints

• Lookup State by ISO Code — same idea for ISO 3166-2 subdivision codes
• Convert ISO Code — translate between alpha-2, alpha-3, and numeric in one call
• Get Country Details — full country record (all fields, tier-gated)