npm Packages

The @countrystatecity monorepo publishes offline data packages, a CLI, and the live API SDK. The data packages work without an API key or network requests; the CLI and SDK call the REST API.

Need data that updates without publishing a new package version, typo-tolerant search, or usage tracking? Pair these packages with the TypeScript SDK — a live API client for when you need that instead of (or alongside) a bundled snapshot. Its Migrating from the Local Packages section has a side-by-side comparison. Get a free API key.

Packages

Package	Environment	Description	Bundle
`@countrystatecity/countries`	Node.js / Server	Countries, states, cities with lazy loading	<10KB
`@countrystatecity/countries-browser`	Browser / Any	Same API as above, loads data via jsDelivr CDN	<10KB
`@countrystatecity/timezones`	Node.js / Server	392 IANA timezones with conversion utilities	<20KB
`@countrystatecity/currencies`	Node.js / Browser	155 ISO 4217 currencies with symbols and formatting	<3KB
`@countrystatecity/translations`	Node.js / Browser	Country name translations in 19 languages	<3KB
`@countrystatecity/phonecodes`	Node.js / Browser	Country phone codes with lookup and formatting	<3KB
`@countrystatecity/postalcodes`	Node.js / Server	Postal codes with locality search and validation	Lazy-loaded
`@countrystatecity/geojson`	Browser / Any	Countries, states, and cities as GeoJSON points	Lazy-loaded
`@countrystatecity/cli`	Terminal	Search, explore, and generate code from geographic data	–
`@countrystatecity/sdk`	Node.js / Browser	Typed client for the live REST API	–

Installation

Install only the packages you need:

# Countries, states, and cities (Node.js / server-side)
npm install @countrystatecity/countries

# Countries, states, and cities (browser / React / Vue / Svelte)
npm install @countrystatecity/countries-browser

# Timezones
npm install @countrystatecity/timezones

# Currencies
npm install @countrystatecity/currencies

# Translations
npm install @countrystatecity/translations

# Phone codes
npm install @countrystatecity/phonecodes

# Postal codes
npm install @countrystatecity/postalcodes

# GeoJSON points
npm install @countrystatecity/geojson

# CLI (global install)
npm install -g @countrystatecity/cli

# Live API SDK
npm install @countrystatecity/sdk

Use @countrystatecity/countries in Node.js, Next.js API routes, or Express. Use @countrystatecity/countries-browser in client-side React, Vue, or Svelte apps — it loads data via CDN instead of bundling it.

Usage

Countries, States, and Cities

import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries';

const countries = await getCountries();
// [{ id: 101, name: 'India', iso2: 'IN', emoji: '🇮🇳', ... }, ...]

const states = await getStatesOfCountry('US');
// [{ id: 1, name: 'California', iso2: 'CA', ... }, ...]

const cities = await getCitiesOfState('US', 'CA');
// [{ id: 110992, name: 'Los Angeles', latitude: '34.05', longitude: '-118.24', ... }, ...]

import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries-browser';

const countries = await getCountries();
// [{ id: 101, name: 'India', iso2: 'IN', emoji: '🇮🇳', ... }, ...]

const states = await getStatesOfCountry('IN');
// [{ id: 1, name: 'Maharashtra', iso2: 'MH', ... }, ...]

const cities = await getCitiesOfState('IN', 'MH');
// [{ id: 1, name: 'Mumbai', ... }, ...]

Timezones

import { getTimezonesByCountry, convertTime, getCurrentTime } from '@countrystatecity/timezones';

const timezones = await getTimezonesByCountry('US');
// [{ zoneName: 'America/New_York', abbreviation: 'EST', gmtOffset: -18000, ... }, ...]

const result = await convertTime(
  '2025-10-18T12:00:00Z',
  'America/New_York',
  'Europe/London'
);
// { originalTime: '2025-10-18T08:00:00', convertedTime: '2025-10-18T13:00:00', timeDifference: 5 }

const now = await getCurrentTime('Asia/Kolkata');
// "2025-10-18T17:30:00.000Z"

Currencies

import { getCurrencyByCode, formatCurrencyAmount, getCurrenciesByCountry } from '@countrystatecity/currencies';

const usd = await getCurrencyByCode('USD');
// { code: 'USD', name: 'US Dollar', symbol: '$', decimalDigits: 2, ... }

const formatted = await formatCurrencyAmount(1234.5, 'USD');
// "$1,234.50"

const currencies = await getCurrenciesByCountry('IN');
// [{ code: 'INR', name: 'Indian Rupee', symbol: '₹', ... }]

Translations

import { getTranslation, getTranslationOrFallback, getCountryTranslations } from '@countrystatecity/translations';

const name = await getTranslation('DE', 'fr');
// "Allemagne"

const entry = await getCountryTranslations('IN');
// { iso2: 'IN', name: 'India', translations: { fr: 'Inde', de: 'Indien', 'zh-CN': '印度', ... } }

getTranslationOrFallback(entry, 'hi');  // "भारत"
getTranslationOrFallback(entry, 'xx');  // "India"  ← falls back to English

Supported locales: ar, br, de, es, fa, fr, hi, hr, it, ja, ko, nl, pl, pt, pt-BR, ru, tr, uk, zh-CN

CLI

# Authenticate with your free API key
csc auth login

# Search countries, states, and cities
csc search countries
csc search states --country IN
csc search cities --country IN --state MH

# Get detailed info as JSON
csc get country US --json

# Interactive browser: pick country → state → view cities or generate code
csc explore

# Generate a React dropdown component (Supporter plan+)
csc generate dropdown --entity countries --format react
csc generate dropdown --entity states --format react --country IN

# Generate a Prisma seed file (Supporter plan+)
csc generate seed --entity countries --format prisma

# Open the online bulk export tool
csc export

Code generation (csc generate) requires a Supporter plan or above. Run csc upgrade to view plans and pricing.

See the CLI page for the full command reference, including typo-tolerant fuzzy search and --fields/--sort.

Data Updates

All packages update automatically every week via a CI pipeline that fetches the latest data from the countries-states-cities-database, runs tests, and publishes a patch release to npm. To get the latest data in your project, update the package:

npm update @countrystatecity/countries

Checking your installed data version

Both @countrystatecity/countries and @countrystatecity/countries-browser export a getDataVersion() loader so you can confirm which release your installed package is bundling, without loading the full dataset:

import { getDataVersion } from '@countrystatecity/countries';

const version = await getDataVersion();
// {
//   dataVersion: 'v3.2-export.7-2026.07.29',
//   sourceRelease: 'v3.2-export.7',
//   updatedAt: '2026-07-29T09:01:18Z',
//   recordCounts: { countries: 250, states: 5308, cities: 152970 }
// }

The counts above are from one release and are illustrative — they change every time the data is refreshed.

Comparing your package against the live API

The Get Data Version endpoint returns the same three fields for the data the API is serving. Compare sourceRelease, not dataVersion. Both sides build dataVersion from the same release tag, but they append different dates: the package uses the date the release was published, while the API uses the date that release was imported. Because the import happens after the release is published, the two strings usually differ by a day or more even when both sides hold exactly the same data. sourceRelease is identical on both sides, so it is the reliable parity key.

import { getDataVersion } from '@countrystatecity/countries';

async function isPackageInSyncWithApi(apiKey: string): Promise<boolean | null> {
  const local = await getDataVersion();

  const response = await fetch('https://api.countrystatecity.in/v1/meta/data-version', {
    headers: { 'X-CSCAPI-KEY': apiKey }
  });

  if (!response.ok) {
    console.error(`Could not read the live data version (HTTP ${response.status})`);
    return null;
  }

  const live = await response.json();

  // Compare sourceRelease — the dataVersion date suffixes differ by design.
  return local.sourceRelease === live.sourceRelease;
}

const inSync = await isPackageInSyncWithApi('YOUR_API_KEY');
console.log(inSync); // true

The API’s version metadata is cached and can trail a fresh import by about 5 minutes (about 5.5 minutes for the X-CSC-Data-* response headers). If a comparison comes back out of sync right after a data refresh, retry a few minutes later before treating it as a real mismatch.

The package’s recordCounts is narrower than the API’s — countries/states/cities only, no regions/subregions.

API Documentation

Countries Endpoints

States Endpoints

Cities Endpoints

Regions Endpoints

Currency Endpoints

ISO Code Endpoints

Phone Endpoints

Timezone Endpoints

Search Endpoints

Data Changes

Postcode Endpoints

Meta Endpoints

SDKs & Examples

No-Code Integrations

Packages

Installation

Usage

Countries, States, and Cities

Timezones

Currencies

Translations

CLI

Data Updates

Checking your installed data version

Comparing your package against the live API

Source

GitHub Repository

npm Organization

​Packages

​Installation

​Usage

​Countries, States, and Cities

​Timezones

​Currencies

​Translations

​CLI

​Data Updates

​Checking your installed data version

​Comparing your package against the live API

​Source

GitHub Repository

npm Organization

Packages

Installation

Usage

Countries, States, and Cities

Timezones

Currencies

Translations

CLI

Data Updates

Checking your installed data version

Comparing your package against the live API

Source