State API

The layer most country datasets skip.

States, provinces and other administrative divisions linked to their parent country. Subdivision codes, division types and other fields depend on the record and your plan.

5,300+ states and regions
JSON responses
3,000 free requests / mo

Coverage varies by release. Check the API statistics and database releases for current data. Read the ODbL-1.0 licence before using the database.

Request200 OK
curl --location 'https://api.countrystatecity.in/v1/countries/IN/states/MH' \
  --header 'X-CSCAPI-KEY: YOUR_API_KEY'
Community response excerpt
{
  "id": 4008,
  "name": "Maharashtra",
  "iso2": "MH",
  "country_id": 101,
  "country_code": "IN"
}

Endpoints

These endpoints are served from https://api.countrystatecity.in/v1 and require your key in the X-CSCAPI-KEY header. Availability depends on your plan.

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

Available fields for state records.

Fields depend on your plan and may be missing or null. On eligible plans, select fields with ?fields=. Compare plan access.

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
populationWhen available; may be null
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".
Build a React location dropdown with the browser package →

Questions.

Which countries have state data?

Coverage varies by country and territory. Records can represent different administrative levels. Use /countries/{ciso}/states to inspect the current entries for a country; some places may have no listed divisions.

Do you return ISO 3166-2 codes?

The iso3166_2 field contains a subdivision code when available, alongside iso2. Some records lack a code, and field access depends on your plan.

What does the type field contain?

A division classification such as state, province, region or prefecture, when available. Values and administrative levels vary by record and country; access to this field depends on your plan.

Can I fetch every state in one request?

GET /states lists states on Starter and higher plans. Community includes /countries/{ciso}/states for a country-by-country load. Check the current plan comparison for endpoint availability.

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.