Skip to main content
GET
/
v1
/
iso
/
state
curl -X GET 'https://api.countrystatecity.in/v1/iso/state?iso=US-CA' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

{
  "id": 1416,
  "name": "California",
  "iso2": "CA",
  "iso3166_2": "US-CA",
  "country_id": 233,
  "country_code": "US"
}
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 -X GET 'https://api.countrystatecity.in/v1/iso/state?iso=US-CA' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

{
  "id": 1416,
  "name": "California",
  "iso2": "CA",
  "iso3166_2": "US-CA",
  "country_id": 233,
  "country_code": "US"
}