npm Packages

The @countrystatecity monorepo publishes six packages to npm. All data is bundled directly — no API key or network requests needed (except the CLI, which calls the REST API).

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/cli`	Terminal	Search, explore, and generate code from geographic data	–

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

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

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.

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

API Documentation

Countries Endpoints

States Endpoints

Cities Endpoints

Regions Endpoints

Currency Endpoints

ISO Code Endpoints

Phone Endpoints

Timezone Endpoints

Search Endpoints

SDKs & Examples

No-Code Integrations

Packages

Installation

Usage

Countries, States, and Cities

Timezones

Currencies

Translations

CLI

Data Updates

Source

GitHub Repository

npm Organization

​Packages

​Installation

​Usage

​Countries, States, and Cities

​Timezones

​Currencies

​Translations

​CLI

​Data Updates

​Source

GitHub Repository

npm Organization

Packages

Installation

Usage

Countries, States, and Cities

Timezones

Currencies

Translations

CLI

Data Updates

Source