Skip to main content
The @countrystatecity monorepo publishes five packages to npm. All data is bundled directly — no API key or network requests needed.

​
Packages

PackageEnvironmentDescriptionBundle
@countrystatecity/countriesNode.js / ServerCountries, states, cities with lazy loading<10KB
@countrystatecity/countries-browserBrowser / AnySame API as above, loads data via jsDelivr CDN<10KB
@countrystatecity/timezonesNode.js / Server392 IANA timezones with conversion utilities<20KB
@countrystatecity/currenciesNode.js / Browser155 ISO 4217 currencies with symbols and formatting<3KB
@countrystatecity/translationsNode.js / BrowserCountry name translations in 19 languages<3KB

​
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
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', ... }, ...]

​
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

​
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

​
Source

GitHub Repository

View the monorepo source, open issues, or contribute.

npm Organization

Browse all published packages on npm.