world-location-data

A comprehensive npm package providing detailed location data for 250+ countries, 5,000+ states/provinces, and 150,000+ cities worldwide. Perfect for building location-based features, dropdowns, search systems, and geographic applications.

Features

• 250+ Countries with rich metadata
• 5,000+ States/Provinces with administrative details
• 150,000+ Cities - Most comprehensive dataset available
• Zero Dependencies - Pure JSON data
• TypeScript Support - Full type definitions included
• Tree-shakeable - Import only what you need
• Lazy Loading - Efficient memory usage with data caching
• Rich Metadata including:
  • ISO codes (ISO2, ISO3)
  • Phone codes
  • Currencies with symbols
  • Timezones with GMT offsets
  • Coordinates (latitude/longitude)
  • Translations in 15+ languages
  • Population & GDP data
  • Regions & subregions
  • Native names

Installation

npm install world-location-data

Quick Start

import {
  getAllCountries,
  getCountryByCode,
  getStatesByCountryCode,
  getCitiesByCountryCode,
} from 'world-location-data';

// Get all countries
const countries = getAllCountries();

// Get a specific country by ISO code
const usa = getCountryByCode('US');
console.log(usa.name); // "United States"
console.log(usa.capital); // "Washington"
console.log(usa.currency); // "USD"

// Get states/provinces for a country
const usStates = getStatesByCountryCode('US');

// Get cities for a country
const usCities = getCitiesByCountryCode('US');

API Reference

Countries

getAllCountries(): Country[]

Get all countries with complete metadata.

const countries = getAllCountries();

getCountryById(id: number): Country | undefined

Get a country by its numeric ID.

const country = getCountryById(231); // United States

getCountryByCode(code: string): Country | undefined

Get a country by ISO2 or ISO3 code.

const usa = getCountryByCode('US');
const usaAlt = getCountryByCode('USA');

getCountryByName(name: string, exact?: boolean): Country | undefined

Get a country by name (case-insensitive by default).

const country = getCountryByName('United States');

searchCountries(options: SearchOptions): Country[]

Search countries by name, capital, or ISO codes.

const results = searchCountries({
  query: 'united',
  limit: 10,
  caseSensitive: false
});

filterCountries(filters: FilterOptions): Country[]

Filter countries by multiple criteria.

const europeanCountries = filterCountries({
  region: 'Europe',
  currency: 'EUR'
});

getCountriesByRegion(region: string): Country[]

Get all countries in a specific region.

const asianCountries = getCountriesByRegion('Asia');

getCountriesBySubregion(subregion: string): Country[]

Get all countries in a specific subregion.

const southeastAsian = getCountriesBySubregion('South-Eastern Asia');

getCountriesByCurrency(currency: string): Country[]

Get all countries using a specific currency.

const euroCountries = getCountriesByCurrency('EUR');

getCountryByPhoneCode(phonecode: string): Country[]

Get countries by phone code.

const countries = getCountryByPhoneCode('+1');

getCountriesNearCoordinates(options: CoordinateOptions): Country[]

Find countries near specific coordinates.

const nearbyCountries = getCountriesNearCoordinates({
  latitude: 40.7128,
  longitude: -74.0060,
  radius: 500 // kilometers
});

getAllRegions(): string[]

Get a list of all unique regions.

const regions = getAllRegions();
// ["Africa", "Americas", "Asia", "Europe", "Oceania"]

getAllSubregions(): string[]

Get a list of all unique subregions.

const subregions = getAllSubregions();

getAllCurrencies(): Array<{code: string, name: string, symbol: string}>

Get a list of all currencies.

const currencies = getAllCurrencies();

States

getAllStates(): State[]

Get all states/provinces.

const states = getAllStates();

getStateById(id: number): State | undefined

Get a state by its numeric ID.

const state = getStateById(1416);

getStateByCode(code: string, countryCode?: string): State | undefined

Get a state by ISO code, optionally filtered by country.

const california = getStateByCode('CA', 'US');

getStatesByCountryId(countryId: number): State[]

Get all states for a specific country ID.

const states = getStatesByCountryId(231);

getStatesByCountryCode(countryCode: string): State[]

Get all states for a specific country code.

const usStates = getStatesByCountryCode('US');

searchStates(options: SearchOptions, countryId?: number): State[]

Search states by name.

const results = searchStates(
  { query: 'new', limit: 5 },
  231 // USA
);

getStatesNearCoordinates(options: CoordinateOptions, countryId?: number): State[]

Find states near specific coordinates.

const nearbyStates = getStatesNearCoordinates({
  latitude: 40.7128,
  longitude: -74.0060,
  radius: 100
}, 231);

getStatesByType(type: string, countryId?: number): State[]

Get states by administrative type (province, state, etc.).

const provinces = getStatesByType('province', 38); // Canadian provinces

Cities

getAllCities(): City[]

Get all cities (150K+ cities - use with caution).

const cities = getAllCities();

getCityById(id: number): City | undefined

Get a city by its numeric ID.

const city = getCityById(1840);

getCitiesByCountryId(countryId: number): City[]

Get all cities for a specific country ID.

const usCities = getCitiesByCountryId(231);

getCitiesByCountryCode(countryCode: string): City[]

Get all cities for a specific country code.

const usCities = getCitiesByCountryCode('US');

getCitiesByStateId(stateId: number): City[]

Get all cities for a specific state ID.

const californiaCities = getCitiesByStateId(1416);

getCitiesByStateCode(stateCode: string, countryCode?: string): City[]

Get all cities for a specific state code.

const californiaCities = getCitiesByStateCode('CA', 'US');

searchCities(options: SearchOptions, countryId?: number, stateId?: number): City[]

Search cities by name.

const results = searchCities(
  { query: 'los', limit: 10 },
  231, // USA
  1416  // California
);

getCitiesNearCoordinates(options: CoordinateOptions, countryId?: number, stateId?: number): City[]

Find cities near specific coordinates.

const nearbyCities = getCitiesNearCoordinates({
  latitude: 34.0522,
  longitude: -118.2437,
  radius: 50
}, 231, 1416);

getCityByName(name: string, countryCode?: string, stateCode?: string): City | undefined

Get a specific city by name.

const la = getCityByName('Los Angeles', 'US', 'CA');

Utilities

calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number

Calculate distance between two coordinates using the Haversine formula. Returns distance in kilometers.

import { calculateDistance } from 'world-location-data';

const distance = calculateDistance(40.7128, -74.0060, 34.0522, -118.2437);
console.log(distance); // Distance in kilometers

clearCache(): void

Clear cached data to free memory.

import { clearCache } from 'world-location-data';

clearCache();

TypeScript Types

interface Country {
  id: number;
  name: string;
  iso3: string;
  iso2: string;
  numeric_code: string;
  phonecode: string;
  capital: string;
  currency: string;
  currency_name: string;
  currency_symbol: string;
  tld: string;
  native: string;
  population: number;
  gdp: number | null;
  region: string;
  region_id: number;
  subregion: string;
  subregion_id: number;
  nationality: string;
  timezones: Timezone[];
  translations: Translations;
  latitude: string;
  longitude: string;
  emoji?: string;
  emojiU?: string;
}

interface State {
  id: number;
  name: string;
  country_id: number;
  country_code: string;
  country_name: string;
  iso2: string;
  iso3166_2: string;
  fips_code: string;
  type: string;
  level: string | null;
  parent_id: number | null;
  native: string;
  latitude: string;
  longitude: string;
  timezone: string;
}

interface City {
  id: number;
  name: string;
  state_id: number;
  state_code: string;
  state_name: string;
  country_id: number;
  country_code: string;
  country_name: string;
  latitude: string;
  longitude: string;
  timezone: string | null;
  wikiDataId: string;
}

Use Cases

Country Selector Dropdown

import { getAllCountries } from 'world-location-data';

const countries = getAllCountries();
const countryOptions = countries.map(c => ({
  value: c.iso2,
  label: c.name,
  flag: c.emoji
}));

Hierarchical Location Picker

import {
  getCountryByCode,
  getStatesByCountryCode,
  getCitiesByStateCode
} from 'world-location-data';

// User selects country
const country = getCountryByCode('US');

// Load states for that country
const states = getStatesByCountryCode('US');

// User selects state
const cities = getCitiesByStateCode('CA', 'US');

Phone Number Input with Country Code

import { getAllCountries } from 'world-location-data';

const phoneCodeOptions = getAllCountries().map(c => ({
  code: c.phonecode,
  country: c.name,
  flag: c.emoji
}));

Currency Converter

import { getAllCurrencies, getCountriesByCurrency } from 'world-location-data';

const currencies = getAllCurrencies();
const euroCountries = getCountriesByCurrency('EUR');

Location-based Search

import { getCitiesNearCoordinates } from 'world-location-data';

// Find cities near user's location
navigator.geolocation.getCurrentPosition(position => {
  const nearbyCities = getCitiesNearCoordinates({
    latitude: position.coords.latitude,
    longitude: position.coords.longitude,
    radius: 50
  });
});

Performance Tips

1. Lazy Loading: Data is automatically cached on first access. Only call the functions you need.

2. Filter Before Loading: Use specific queries instead of loading all data:

   // Good
   const californiaCities = getCitiesByStateCode('CA', 'US');
   
   // Avoid (150K+ cities)
   const allCities = getAllCities();

3. Tree Shaking: Import only what you need:

   import { getCountryByCode } from 'world-location-data';

4. Clear Cache: Free memory when done with large datasets:

   import { clearCache } from 'world-location-data';
   clearCache();

Data Sources

This package uses data from the dr5hn/countries-states-cities-database repository, which is regularly maintained and updated.

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository

https://github.com/zubair-ra/world-location-data

Support

For issues, questions, or suggestions, please open an issue on GitHub