Ecosystem
One dataset.
Nine ways to use it.
Every channel is built from the same open database, with the same IDs. Start with one, switch or combine later without remapping anything.
REST APITiered, high-availability
GET /v1/countriesPick the channel that fits how you work.
Grouped by what you're trying to do. Every channel is kept in sync from one source of truth.
BuildPut the data inside your product.
REST API
Tiered, high-availabilityCountries, states, cities, search and more over HTTPS. Free tier included.Learn more →npm packages10 packages
JavaScript and TypeScriptAn official API SDK, a CLI, and eight offline data packages for Node and the browser.Learn more →PyPI packages8 packages
Python-first ergonomicsA typed sync + async API client, plus seven offline data packages.Learn more →CLI
Search, export, scaffoldSearch, explore interactively, and generate React dropdowns or Prisma seeds.Learn more →DataGet the whole dataset, or just the slice you need.
Database★ 9.8K
The canonical sourceThe full open dataset on GitHub, in 12 formats. Everything else is built from it.Learn more →Export Tool13 formats
Bulk data on demandPick regions and fields, download a clean file. 5 free credits to start.Learn more →ExploreLook around before you commit.
Playground
Interactive Swagger UITry every endpoint in the browser before writing code.Learn more →Live Demo
Browse the datasetExplore countries, states and cities without an account.Learn more →CommunityHelp keep the data accurate.
Update Tool
Submit & track correctionsSuggest a fix, follow its review and see it ship in the next release.Learn more →Packages
Install it the way you work.
Versioned packages with types included. Offline data packages use ODbL-1.0; the npm API SDK and CLI use MIT. Check each package before use. Node snapshots need no network; countries-browser loads data from a CDN.
Node.js and browser · TypeScript types included
Live
@countrystatecity/sdkOfficial REST API clientnpm install @countrystatecity/sdk
Tool
@countrystatecity/cliSearch, explore, generate codenpm install -g @countrystatecity/cli
Offline
@countrystatecity/countriesCountries, states, cities · Nodenpm install @countrystatecity/countries
Offline
@countrystatecity/countries-browserSame API, loads via CDNnpm install @countrystatecity/countries-browser
Offline
@countrystatecity/timezonesIANA timezone datanpm install @countrystatecity/timezones
Offline
@countrystatecity/currenciesISO 4217 currency datanpm install @countrystatecity/currencies
Offline
@countrystatecity/translationsNames in 19 languagesnpm install @countrystatecity/translations
Offline
@countrystatecity/phonecodesCountry dial codesnpm install @countrystatecity/phonecodes
Offline
@countrystatecity/postalcodes844,000+ codes, 125 countriesnpm install @countrystatecity/postalcodes
Offline
@countrystatecity/geojsonPoint FeatureCollectionsnpm install @countrystatecity/geojson
Offline or live
Prototype offline. Go live when you ship.
Packages are frozen snapshots, perfect for dev, tests and dropdowns. Switch to the API for fresh data, fuzzy search and support. IDs link the records; snapshot contents vary by release.
Offline packageno key · no network
import { getStatesOfCountry, getCitiesOfState }
from '@countrystatecity/countries';
const states = await getStatesOfCountry('IN');
const cities = await getCitiesOfState('IN', 'MH');Live API client3,000 free requests / mo
import { createCSCClient } from '@countrystatecity/sdk';
const csc = createCSCClient({ apiKey: process.env.CSC_API_KEY });
const { data: states } = await csc.states.list({ country: 'IN' });
const hits = await csc.search.fuzzy({ query: 'bangalor', type: 'city' });Not sure where to start?
Most teams start with the API: 3,000 free requests a month, no card needed.