{ "error": "Unauthorized. You shouldn't be here."}
Retrieve all cities within a specific state or province using both the country’s ISO2 code and the state’s ISO2 code. This provides the most targeted city data.
Availability: All plans (Community and above). The fields returned 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.
City responses on the Basic tier return id, name, and kind. Upgrading to Supporter+ unlocks the full field set: state_id, state_code, country_id, country_code, latitude, longitude, timezone, population, type, level, parent_id, native, translations, and wikiDataId. See Tier-Based Field Availability below.
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?q=pune' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?kind=settlement' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities?include_translations=true' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requestsdef get_cities_by_state(country_code, state_code): response = requests.get( f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}/cities', headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'} ) if response.ok: cities = response.json() print(f'Found {len(cities)} cities in {state_code}, {country_code}') return cities else: print('State not found or no cities available') return []cities = get_cities_by_state('IN', 'MH')
import requestsdef get_settlements_by_state(country_code, state_code): response = requests.get( f'https://api.countrystatecity.in/v1/countries/{country_code}/states/{state_code}/cities', params={'kind': 'settlement'}, headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'} ) if response.ok: cities = response.json() print(f'Found {len(cities)} settlements in {state_code}, {country_code}') return cities else: print('State not found or no cities available') return []cities = get_settlements_by_state('IN', 'MH')
const getCitiesByState = async (countryCode, stateCode) => { const response = await fetch( `https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}/cities`, { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } } ); if (response.ok) { const cities = await response.json(); console.log(`Found ${cities.length} cities in ${stateCode}, ${countryCode}`); return cities; } else { console.error('State not found or no cities available'); return []; }};getCitiesByState('IN', 'MH');
const getSettlementsByState = async (countryCode, stateCode) => { const response = await fetch( `https://api.countrystatecity.in/v1/countries/${countryCode}/states/${stateCode}/cities?kind=settlement`, { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } } ); if (response.ok) { const cities = await response.json(); console.log(`Found ${cities.length} settlements in ${stateCode}, ${countryCode}`); return cities; } else { console.error('State not found or no cities available'); return []; }};getSettlementsByState('IN', 'MH');
<?phpfunction getCitiesByState($countryCode, $stateCode) { $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.countrystatecity.in/v1/countries/{$countryCode}/states/{$stateCode}/cities", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => array( 'X-CSCAPI-KEY: YOUR_API_KEY' ), )); $response = curl_exec($curl); $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($httpCode == 200) { $cities = json_decode($response, true); echo "Found " . count($cities) . " cities in {$stateCode}, {$countryCode}\n"; return $cities; } else { echo "State not found or no cities available\n"; return []; }}$cities = getCitiesByState('IN', 'MH');?>
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:
"mum"
kind
string
Filter by derived place classification. Comma-separated list of settlement, administrative, section, unknown. Free on every plan. Invalid values return 400 listing the accepted values.
Example:
"settlement"
type
string
Filter by the raw source type value. Comma-separated, e.g. city,adm2. Requires Supporter+ plan (type is an extended field); lower plans receive 400 rather than the filter being ignored. Unrecognised values match zero rows.
Example:
"city"
fields
string
Comma-separated list of fields to include in the response. id is always included. Requires Starter+ plan.
Example:
"name,latitude,longitude"
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 cities
id
integer<int64>
required
Unique identifier
Example:
57606
name
string
required
City name in English
Example:
"Mumbai"
kind
enum<string>
Derived classification of the place, computed from type. Returned on every tier, including Basic. See City Types.
Available options:
settlement,
administrative,
section,
unknown
Example:
"settlement"
state_id
integer<int64>
Parent state ID. Coordinates tier and above.
state_code
string
Parent state ISO2 code. Coordinates tier and above.
Example:
"MH"
country_id
integer<int64>
Parent country ID. Coordinates tier and above.
country_code
string
Parent country ISO2 code. Coordinates tier and above.
Example:
"IN"
latitude
string
Latitude coordinate. Coordinates tier and above.
Example:
"19.07283000"
longitude
string
Longitude coordinate. Coordinates tier and above.
Example:
"72.88261000"
timezone
string | null
IANA timezone identifier. Coordinates tier and above.
Example:
"Asia/Kolkata"
population
integer<int64> | null
Population count. Coordinates tier and above.
type
string | null
Raw source settlement type, e.g. city, adm2. See City Types. Coordinates tier and above.
level
integer | null
Administrative level. Coordinates tier and above.
parent_id
integer<int64> | null
Parent city ID. Coordinates tier and above.
native
string | null
Name in native language. 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:
"Q1156"
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:
"Mumbai"
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.