Official npm packages

Geographic data, straight from npm.

Nine packages under the @countrystatecity scope, published from the same dataset the API serves. Install the slice you need, ship it with your bundle, and make no network call at runtime.

npm install @countrystatecity/countries

The packages.

Each one stands alone, so a phone input does not have to ship 153,765 cities.

@countrystatecity/countriesCountries, states and cities with minified builds and iOS/Safari support. The one to start with if you only install a single package.
npm i @countrystatecity/countries
@countrystatecity/countries-browserThe same data served over the jsDelivr CDN with lazy loading, for pages that should not carry it in the bundle.
npm i @countrystatecity/countries-browser
@countrystatecity/timezonesTimezone data with conversion helpers, so you can show a user their local time without asking for it.
npm i @countrystatecity/timezones
@countrystatecity/currenciesWorld currencies with ISO 4217 codes, symbols and the countries that use them.
npm i @countrystatecity/currencies
@countrystatecity/phonecodesDial codes mapped to ISO2, with search and formatting helpers for phone inputs.
npm i @countrystatecity/phonecodes
@countrystatecity/postalcodesPostal and ZIP codes with locality search and existence-based validation, rather than a regex that guesses.
npm i @countrystatecity/postalcodes
@countrystatecity/geojsonCountries, states and cities as GeoJSON Point FeatureCollections, loaded over the CDN for maps.
npm i @countrystatecity/geojson
@countrystatecity/translationsCountry names in 19 languages, including Arabic, German, French and Spanish.
npm i @countrystatecity/translations
@countrystatecity/cliThe official command-line client: search the data, explore the hierarchy and generate request code.
npm i @countrystatecity/cli

Package or API?

Reach for a package when
  • the data ships with your build and has to work offline
  • a dropdown should open with no round trip
  • you can redeploy to pick up a data correction
Reach for the API when
  • corrections should reach users the day they land
  • you want fuzzy search, autocomplete or nearby lookups
  • bundle size matters more than one request
Get free API key →Read the SDK docs

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?

No. The data ships inside the package and resolves locally, so there is no network call and nothing to authenticate. A key is only needed for the hosted API.

How do the packages relate to the API?

They are built from the same dataset. The packages give you a snapshot that updates when you upgrade; the API gives you the current data on every request, plus search, autocomplete and nearby lookups.

Is the data open source?

Yes. The underlying dataset is the countries-states-cities-database project on GitHub, and the packages are published from it.

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.

Data under ODbL, free to use with attribution

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.

Get free API key →Download the database