API requests served · live
Every city, stacked. One request away.
The country, state and city API and open database: 250 countries, 5,300+ states and 150,000+ cities. Use the hosted API or download an offline snapshot.
REST JSON responses
GraphQL Professional and up
ODbL-1.0 open data
World
250+ countries
World
curl "https://api.countrystatecity.in/v1/countries" \ -H "X-CSCAPI-KEY: $API_KEY"
200 OKillustrative sample · 250 results
[
{ "id": 101, "name": "India", "iso2": "IN" },
{ "id": 102, "name": "Indonesia", "iso2": "ID" },
…
]Ecosystem
One dataset. Use it however you build.
Same records, same IDs, in every channel. Switch from the API to a package or a file without remapping anything.
Explore the ecosystem →REST API
HostedCountries, states and cities over HTTPS with an API key.
GET /v1/countries
GraphQL
HostedAsk for a country, its states and their fields in one query.
POST /v1/graphql
npm
10 packagesAn official API SDK, a CLI and eight offline data packages.
npm i @countrystatecity/sdk
PyPI
8 packagesA typed sync + async API client, plus offline data packages.
pip install countrystatecity-api
CLI
ToolSearch, explore and generate dropdowns or seeds from your terminal.
csc search states --country IN
Export Tool
FilesPick data, fields and format. 5 free credits to start.
13 formats · CSV to GeoJSON
Update Tool
CommunitySuggest corrections that ship in the next release.
Submit a change →
Playground
DocsTry any endpoint in the browser before writing code.
Open playground →
GitHub
Open dataRaw data files, releases and issues. ODbL-1.0.
★ 9.8K
The data
Clean, linked records, from region down to city.
Every city knows its state and country. Every country carries ISO codes, currency, phone code, timezones and translations. Updated frequently by the community.
See what each level returns in the Country API, State API and City API guides, or use the data offline with the npm packages.
Coverage varies by release. Check the API statistics and database releases for current data. Read the ODbL-1.0 licence before using the database.
JSONCSVParquetMySQLPostgreSQLSQLiteSQL ServerMongoDBXMLYAMLGeoJSONTOON
countries
states and regions
cities
12
download formatsstatic
In production
What developers build with it.
“Outstanding job on this API! The worldwide country, state, and city data is exactly what our PalGo app needed.”
“Thanks for putting together such a comprehensive location service! The tax calculation features based on user location have been essential for our payment processing.”
“The comprehensive state and city data makes it easy for users across different countries to fill out location information accurately.”
“The comprehensive global data has been perfect for our international darts league platform.”
“The location-based prayer timing functionality works perfectly with the comprehensive country, state, and city data.”
“Excellent job with this API! The credit card processing integration with location data has been seamless and reliable.”
“This export tool has been wonderful for our x509 certificate validation processes!”
“Thanks a lot for this database, this is awesome!”
“Your data is very complete and useful.”
“I'm using your data in other project and it's working just fine. Thanks!”
“The dropdown functionality for country, state, and city selection works flawlessly in our user profile system.”
“This API is really a big help, this is exactly what I was searching for.”
Free to start. Open forever.
The database is open under ODbL-1.0. The API gives you 3,000 free requests a month; paid plans start at $5 and add search, GraphQL and the change feed.
Open source
★ 9.8K on GitHubFound a missing city or a wrong state code? Suggest a fix with the Update Tool; it's reviewed and merged into the next release.
Reviewed in the open · public releases