State API

The layer most country datasets skip.

First-level administrative divisions for all 250 countries, with ISO 3166-2 codes, the official division type and the parent country. The piece most country-only datasets leave out.

Get free API key →Read the docs
5,308 states and regions
19 fields per record
3,000 free requests / mo
Request200 OK
curl --location 'https://api.countrystatecity.in/v1/countries/IN/states/MH' \
  --header 'X-CSCAPI-KEY: YOUR_API_KEY'
Response
{
  "id": 4008,
  "name": "Maharashtra",
  "iso2": "MH",
  "iso3166_2": "IN-MH",
  "country_code": "IN",
  "type": "state",
  "level": 1,
  "latitude": "19.75147980",
  "longitude": "75.71388840",
  "timezone": "Asia/Kolkata",
  "wikiDataId": "Q1191"
}

Endpoints

Every path below is live on https://api.countrystatecity.in/v1 and takes your key in the X-CSCAPI-KEY header.

GET/statesEvery state in the world, one call
GET/countries/{ciso}/statesStates belonging to one country
GET/countries/{ciso}/states/{siso}One state in full
GET/iso/stateLook a state up by its ISO 3166-2 code
GET/timezone/{ciso}/{siso}Timezone for a given state

19 fields on every state.

Take them all, or name the ones you want with ?fields= and keep the response small.

idStable numeric identifier
nameEnglish name
iso2Subdivision part of the ISO code
iso3166_2Full ISO 3166-2 code
country_idParent country id
country_codeParent country ISO2
typestate, province, region, canton and so on
levelDepth in the official hierarchy
parent_idParent division, where one exists
fips_codeFIPS 10-4 code
nativeName in the local script
latitudeCentroid latitude
longitudeCentroid longitude
timezoneIANA zone
populationLatest published figure
translationsName in other languages
wikiDataIdWikidata item

What people build with it.

  • The second dropdown in a country, state and city address form, filtered by the country already chosen.
  • Tax and shipping rules that differ by state, keyed on ISO 3166-2 rather than on a free-text name.
  • Sales territories and reporting regions built on official divisions instead of an internal spreadsheet.
  • Normalising inbound addresses where one system writes "Maharashtra" and another writes "MH".

Questions.

Which countries have state data?

All 250. Coverage is the country's own first-level divisions, so the count varies from one (for small territories) to several hundred, and the type field says what they are called locally.

Do you return ISO 3166-2 codes?

Yes, in the iso3166_2 field, alongside the bare subdivision code in iso2. Use iso3166_2 when you need a globally unique value.

What does the type field contain?

The official name of the division: state, province, region, canton, prefecture, emirate and so on. It comes from the country's own statistical authority, not from a translation.

Can I fetch every state in one request?

Yes, GET /states returns them all. For a country-by-country load, GET /countries/{ciso}/states is smaller and usually what a dropdown wants.

The rest of the hierarchy.

Country API →250 countries, ISO codes, dial codesCity API →153,765 cities with coordinatesOffline database →The same data as SQL, JSON, CSV and more

Free up to 3,000 requests a month.

Paid plans from $5 add higher limits. Supporter adds fuzzy search; Professional adds GraphQL and the change feed.

Get free API key →Compare plans