Geographic data, straight from npm.
10 official packages under the @countrystatecity scope. Choose bundled data for offline use, CDN-loaded snapshots for lazy loading, or the SDK and CLI for authenticated API access.
npm install @countrystatecity/countriesBuild a country, state and city dropdown in React →
The packages.
Install the slice you need: a phone input can use dial codes without bundling the full city dataset.
npm i @countrystatecity/sdk
npm i @countrystatecity/countries
npm i @countrystatecity/countries-browser
npm i @countrystatecity/timezones
npm i @countrystatecity/currencies
npm i @countrystatecity/phonecodes
npm i @countrystatecity/postalcodes
npm i @countrystatecity/geojson
npm i @countrystatecity/translations
npm i @countrystatecity/cli
Package or API?
- a bundled data package can satisfy offline requirements
- a dropdown should open with no round trip
- you can redeploy to pick up a data correction
- you want the data currently served by the API
- you want fuzzy search, autocomplete or nearby lookups
- bundle size matters more than one request
Questions.
Which package should I install first?
@countrystatecity/countries. It carries countries, states and cities together, which is what an address form needs. Add the smaller packages only when you want dial codes, currencies, timezones or postcodes.
Do the packages need an API key?
Bundled data packages work locally without an API key. countries-browser and geojson load snapshots from a CDN and need a network connection when loading. The SDK and API-backed CLI commands call the hosted API and require a key; usage follows your plan.
How do the packages relate to the API?
Data packages provide versioned snapshots of the open database. The SDK and CLI access the hosted API instead. Available fields and endpoints depend on your API plan, and API data and package snapshots can differ by release.
Is the data open source?
The underlying database and offline data packages use ODbL-1.0. The npm SDK and CLI use MIT. Review the licence of each package and the database attribution and share-alike requirements before use.
What about bundle size?
Install only the slice you use. A phone input needs @countrystatecity/phonecodes, not the full city list, and @countrystatecity/countries-browser keeps the data out of your bundle entirely by loading it from a CDN.
Need live data instead of a snapshot?
The API serves the same dataset over REST and GraphQL, with fuzzy search, autocomplete and a change feed.