150,000+ cities and settlements, linked by location.
Cities, towns and settlements linked to countries and states. Community returns basic city fields; richer fields, nearby search and autocomplete are available on eligible paid plans.
Coverage varies by release. Check the API statistics and database releases for current data. Read the ODbL-1.0 licence before using the database.
curl --location 'https://api.countrystatecity.in/v1/countries/IN/states/MH/cities' \ --header 'X-CSCAPI-KEY: YOUR_API_KEY'Community response excerpt
[
{
"id": 133024,
"name": "Mumbai",
"kind": "settlement"
}
]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.
Available fields for city records.
Fields depend on your plan and may be missing or null. On eligible plans, select fields with ?fields=. Compare plan access.
idStable numeric identifiernameEnglish namenativeName in the local scriptkindsettlement, county or administrative unittypecity, town, village and so onlevelDepth in the official hierarchyparent_idContaining division, where one existsstate_idParent state idstate_codeParent state codecountry_idParent country idcountry_codeParent country ISO2latitudePoint latitudelongitudePoint longitudetimezoneIANA zonepopulationWhen available; may be nulltranslationsName in other languageswikiDataIdWikidata itemWhat people build with it.
- The third dropdown in an address form, or a type-ahead that replaces all three.
- Showing the right local time for a user without asking them to pick a timezone.
- Finding the nearest serviceable city to a dropped pin, through /search/nearby.
- Seeding a store locator or coverage map with real coordinates rather than geocoding every row.
Questions.
How many cities does the API cover?
150,000+ cities and settlements across 250 countries and territories. Coverage varies by release. Parent links help identify places with the same name; returned fields depend on your plan.
Is there an autocomplete endpoint?
GET /search/autocomplete returns ranked suggestions across countries, states and cities. It is available on Supporter and higher plans; basic city-list endpoints are also available on Community.
Do cities come with coordinates and timezones?
Coordinates and IANA timezones are included when populated and available on your plan. Some values may be missing or null; Community city responses contain basic fields rather than coordinates.
Can I find cities near a point?
On Supporter and higher plans, GET /search/nearby accepts coordinates and a radius and returns matching places ordered by distance. Check the endpoint documentation for accepted parameters and limits.
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.