{ "error": "Unauthorized. You shouldn't be here."}
Retrieve all cities within a specific country using the country’s ISO2 code. This endpoint is useful for building location selectors and geographical applications.
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.
Availability:/countries/{iso2}/cities (all cities in a country) requires Starter+. Community users must use Get Cities by State instead.
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/cities' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/cities?q=mumbai' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/cities?kind=settlement' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
curl -X GET 'https://api.countrystatecity.in/v1/countries/IN/cities?include_translations=true' \ -H 'X-CSCAPI-KEY: YOUR_API_KEY'
import requestsdef get_cities_by_country(country_code): response = requests.get( f'https://api.countrystatecity.in/v1/countries/{country_code}/cities', headers={'X-CSCAPI-KEY': 'YOUR_API_KEY'} ) if response.ok: cities = response.json() print(f'Found {len(cities)} cities in {country_code}') return cities else: print('Country not found or no cities available') return []cities = get_cities_by_country('IN')
import requestsdef get_settlements_by_country(country_code): response = requests.get( f'https://api.countrystatecity.in/v1/countries/{country_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 {country_code}') return cities else: print('Country not found or no cities available') return []cities = get_settlements_by_country('IN')
const getCitiesByCountry = async (countryCode) => { const response = await fetch(`https://api.countrystatecity.in/v1/countries/${countryCode}/cities`, { headers: { 'X-CSCAPI-KEY': 'YOUR_API_KEY' } }); if (response.ok) { const cities = await response.json(); console.log(`Found ${cities.length} cities in ${countryCode}`); return cities; } else { console.error('Country not found or no cities available'); return []; }};getCitiesByCountry('IN');
const getSettlementsByCountry = async (countryCode) => { const response = await fetch( `https://api.countrystatecity.in/v1/countries/${countryCode}/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 ${countryCode}`); return cities; } else { console.error('Country not found or no cities available'); return []; }};getSettlementsByCountry('IN');
Large Datasets: Countries like the United States, India, and China have thousands of cities. Consider implementing pagination or using the state-filtered endpoint for better performance.
For better user experience, consider loading cities by state instead of by country for countries with many administrative divisions.
Tier-Based Field Availability
This endpoint requires Starter+ (Legacy plans also include it), so Community accounts never reach field access at all — they get a 403 first.
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.