{ "error": "Unauthorized. You shouldn't be here."}
Retrieve a complete list of all states, provinces, regions, and territories from around the world with basic geographical information.
Availability: Starter plan and above. Calling /states without filtering by country (bulkStates) is gated to Starter+. Community users must call /countries/{iso2}/states instead. The fields returned also vary by tier — see Tier-Based Field Availability below.
Trim and order results: Add ?fields= to limit columns returned, or ?sort= to order the list. Both are available on Starter+ plans. See the Field Filtering & Sorting guide for syntax and per-entity sortable fields.
Additional fields like fips_code, iso3166_2, level, parent_id, native, population, translations, and wikiDataId are returned on higher tiers. See Tier-Based Field Availability below.
curl -X GET 'https://api.countrystatecity.in/v1/states' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/states?q=texas' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/states?include_translations=true' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
translations is part of Full access but is not returned by default: add include_translations=true, or name it in ?fields=. localized_name and matched_locale are computed from the translations rather than stored, and appear only when you pass locale. See Localized Place Names.See Pricing for plan details.
Search filter. Case-insensitive match on name and native fields. Min 2 characters. Requires Starter+ plan.
Required string length: 2 - 100
Example:
"maha"
fields
string
Comma-separated list of fields to include in the response. id is always included. Requires Starter+ plan.
Example:
"name,iso2,country_code"
sort
string
Comma-separated sort tokens: field or field:asc|desc. Requires Starter+ plan.
Example:
"name:asc"
locale
string
BCP 47 locale code (e.g. pt-BR) to request a localized name. Adds localized_name (resolved via exact locale → base language → native name → English name fallback) and matched_locale (which tier matched) to each result; name is unaffected. Supporter+ plans only — silently omitted (not an error) on lower tiers. A malformed value is rejected with a 400 on every tier.
Required string length: 2 - 7
Pattern: ^[a-zA-Z]{2}(-[a-zA-Z]{2,4})?$
Example:
"pt-BR"
include_translations
boolean
default:false
When true, includes the full translations field (JSON string keyed by language code). Supporter+ plans only — silently omitted (not an error) on lower tiers. Note that an explicit fields=translations also returns the field and takes precedence over this flag.
Example:
true
Response
List of all states globally
id
integer<int64>
required
Unique identifier
Example:
4008
name
string
required
State name in English
Example:
"Maharashtra"
country_id
integer<int64>
required
Parent country ID
country_code
string
required
Parent country ISO2 code
Example:
"IN"
iso2
string | null
State/province ISO code
Example:
"MH"
latitude
string | null
Latitude coordinate
Example:
"19.75147980"
longitude
string | null
Longitude coordinate
Example:
"75.71388840"
timezone
string | null
IANA timezone identifier
Example:
"Asia/Kolkata"
fips_code
string | null
FIPS code. Coordinates tier and above.
iso3166_2
string | null
ISO 3166-2 subdivision code. Coordinates tier and above.
type
string | null
Administrative type (e.g., state, province, territory). Coordinates tier and above.
Example:
"state"
level
integer | null
Administrative level. Coordinates tier and above.
parent_id
integer<int64> | null
Parent subdivision ID (for nested administrative structures). Coordinates tier and above.
native
string | null
Name in native language. Coordinates tier and above.
population
integer<int64> | null
Population count. Coordinates tier and above.
translations
string | null
JSON string keyed by language code. Supporter+ plans only. Returned when include_translations=true or when fields=translations explicitly requests it.
wikiDataId
string | null
Wikidata item identifier. Full access level only.
Example:
"Q1191"
localized_name
string | null
Name resolved via the locale query param's fallback chain (exact locale → base language → native name → English name). Only present when locale was supplied. Supporter+ plans only — silently omitted on lower tiers.
Example:
"Maharashtra"
matched_locale
string | null
Which fallback tier satisfied the locale request: the exact locale (e.g. pt-BR), its base language (e.g. pt), native, or en (English fallback). Only present when locale was supplied. Supporter+ plans only — silently omitted on lower tiers.