curl -X GET 'https://api.countrystatecity.in/v1/iso/state?iso=US-CA' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/iso/state?iso=in-mh' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
const response = await fetch(
'https://api.countrystatecity.in/v1/iso/state?iso=US-CA',
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
const state = await response.json();
console.log(`${state.name}, ${state.country_code} (id ${state.id})`);
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/iso/state',
params={'iso': 'DE-BY'},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
state = response.json()
print(state['name']) # "Bavaria"
{
"id": 1416,
"name": "California",
"iso2": "CA",
"iso3166_2": "US-CA",
"country_id": 233,
"country_code": "US"
}
{
"id": 4022,
"name": "Maharashtra",
"iso2": "MH",
"iso3166_2": null,
"country_id": 101,
"country_code": "IN"
}
{
"status": "error",
"message": "Invalid query parameters: iso: is required (e.g. iso=US-CA)"
}
{
"status": "error",
"message": "Invalid query parameters: iso: must be an ISO 3166-2 code (e.g. US-CA)"
}
{
"status": "error",
"message": "This feature is not available on your current plan.",
"details": {
"feature": "isoLookup",
"currentTier": "community",
"requiredTier": "starter",
"upgradeUrl": "https://app.countrystatecity.in/pricing"
}
}
{
"status": "error",
"message": "State not found for the given ISO code"
}
ISO Codes
Lookup State by ISO Code
Find a state or province by ISO 3166-2 subdivision code
GET
/
iso
/
state
curl -X GET 'https://api.countrystatecity.in/v1/iso/state?iso=US-CA' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/iso/state?iso=in-mh' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
const response = await fetch(
'https://api.countrystatecity.in/v1/iso/state?iso=US-CA',
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
const state = await response.json();
console.log(`${state.name}, ${state.country_code} (id ${state.id})`);
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/iso/state',
params={'iso': 'DE-BY'},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
state = response.json()
print(state['name']) # "Bavaria"
{
"id": 1416,
"name": "California",
"iso2": "CA",
"iso3166_2": "US-CA",
"country_id": 233,
"country_code": "US"
}
{
"id": 4022,
"name": "Maharashtra",
"iso2": "MH",
"iso3166_2": null,
"country_id": 101,
"country_code": "IN"
}
{
"status": "error",
"message": "Invalid query parameters: iso: is required (e.g. iso=US-CA)"
}
{
"status": "error",
"message": "Invalid query parameters: iso: must be an ISO 3166-2 code (e.g. US-CA)"
}
{
"status": "error",
"message": "This feature is not available on your current plan.",
"details": {
"feature": "isoLookup",
"currentTier": "community",
"requiredTier": "starter",
"upgradeUrl": "https://app.countrystatecity.in/pricing"
}
}
{
"status": "error",
"message": "State not found for the given ISO code"
}
Resolve an ISO 3166-2 subdivision code (e.g.
US-CA, IN-MH, DE-BY) to the state/province record.
The match prefers the canonical iso3166_2 column. When that column is NULL for a row (common in older imports), the endpoint falls back to matching the legacy iso2 column scoped to the same country — so the lookup works even for partially-coded rows without risking cross-country false matches.
Availability: Starter plan and above. Returns
403 on Community plan.Responses are cached server-side for 1 hour. The lookup key is the full ISO 3166-2 code, so
US-CA and us-ca collapse to the same cache slot (input is auto-uppercased).curl -X GET 'https://api.countrystatecity.in/v1/iso/state?iso=US-CA' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/iso/state?iso=in-mh' \
-H 'X-CSCAPI-KEY: YOUR_API_KEY'
const response = await fetch(
'https://api.countrystatecity.in/v1/iso/state?iso=US-CA',
{ headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }
);
const state = await response.json();
console.log(`${state.name}, ${state.country_code} (id ${state.id})`);
import requests
response = requests.get(
'https://api.countrystatecity.in/v1/iso/state',
params={'iso': 'DE-BY'},
headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'}
)
state = response.json()
print(state['name']) # "Bavaria"
{
"id": 1416,
"name": "California",
"iso2": "CA",
"iso3166_2": "US-CA",
"country_id": 233,
"country_code": "US"
}
{
"id": 4022,
"name": "Maharashtra",
"iso2": "MH",
"iso3166_2": null,
"country_id": 101,
"country_code": "IN"
}
{
"status": "error",
"message": "Invalid query parameters: iso: is required (e.g. iso=US-CA)"
}
{
"status": "error",
"message": "Invalid query parameters: iso: must be an ISO 3166-2 code (e.g. US-CA)"
}
{
"status": "error",
"message": "This feature is not available on your current plan.",
"details": {
"feature": "isoLookup",
"currentTier": "community",
"requiredTier": "starter",
"upgradeUrl": "https://app.countrystatecity.in/pricing"
}
}
{
"status": "error",
"message": "State not found for the given ISO code"
}
Related Endpoints
- Lookup Country by ISO Code — country-level ISO lookup (alpha-2/alpha-3/numeric)
- Get State Details — full state record (all fields, tier-gated)
- Get States by Country — all states for a given country
Authorizations
API key for authentication. Get your free key at app.countrystatecity.in.
Query Parameters
ISO 3166-2 subdivision code (e.g., US-CA or IN-MH). Case-insensitive.
Example:
"US-CA"
Response
State record with ISO identifiers and country reference
State record returned by the ISO 3166-2 lookup endpoint.
Internal CSC state ID
Example:
1416
State name in English
Example:
"California"
Parent country ID
Example:
233
Parent country ISO2 code
Example:
"US"
Legacy state ISO2 code
Example:
"CA"
ISO 3166-2 subdivision code
Example:
"US-CA"