Lookup State by ISO Code

Find a state or province by ISO 3166-2 subdivision code

GET /v1/iso/state

cURL

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"

200 - Success

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

{
  "error": "Invalid query parameters: iso: is required (e.g. iso=US-CA)"
}

{
  "error": "Invalid query parameters: iso: must be an ISO 3166-2 code (e.g. US-CA)"
}

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

{
  "error": "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).

Authentication

X-CSCAPI-KEY · string · required

Your API key for authentication

Query Parameters

iso · string · required

ISO 3166-2 subdivision code in the form XX-YYY — 2-letter country code, hyphen, then 1–3 alphanumeric characters for the subdivision. Case-insensitive (auto-uppercased).

Examples: US-CA, IN-MH, DE-BY, GB-ENG, JP-13

Response

id · integer

Internal CSC state ID — same value used by /v1/states/:id and as a foreign key from /cities.

name · string

Official state/province name in English (e.g. "California").

iso2 · string | null

Legacy subdivision code without the country prefix (e.g. "CA"). May be null for some entries.

iso3166_2 · string | null

Canonical ISO 3166-2 code (e.g. "US-CA"). May be null for older entries — the endpoint still resolves them via the iso2 fallback.

country_id · integer

Internal CSC country ID — foreign key into /countries.

country_code · string

ISO 3166-1 alpha-2 code of the parent country (e.g. "US").

cURL

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"

200 - Success

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

{
  "error": "Invalid query parameters: iso: is required (e.g. iso=US-CA)"
}

{
  "error": "Invalid query parameters: iso: must be an ISO 3166-2 code (e.g. US-CA)"
}

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

{
  "error": "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