Official npm packages

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/countries
Build 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.

@countrystatecity/sdkThe official JavaScript/TypeScript REST API client. Makes network requests and requires a CSC API key; endpoints and quotas follow your API plan.
npm i @countrystatecity/sdk
@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 API command-line client: authenticate with an API key, search data, explore the hierarchy and generate request code. API-backed commands need a network connection.
npm i @countrystatecity/cli

Package or API?

Reach for a package when
  • 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
Reach for the API when
  • 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.

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.