{"_id":"@anrivera/countries-states-cities-database","name":"@anrivera/countries-states-cities-database","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@anrivera/countries-states-cities-database","version":"1.0.0","description":"Open dataset of countries, states and cities in JSON","main":"index.js","types":"types/index.d.ts","license":"MIT","keywords":["countries","states","cities","regions","subregions","json","database","geography"],"repository":{"type":"git","url":"git+https://github.com/anrivera/region-countries-states-cities-JSON.git"},"scripts":{"validate":"node scripts/validate-data.js","split-cities":"node scripts/split-cities.js"},"_id":"@anrivera/countries-states-cities-database@1.0.0","gitHead":"cb79871751b438fd5f6602d47f89710de36486d2","bugs":{"url":"https://github.com/anrivera/region-countries-states-cities-JSON/issues"},"homepage":"https://github.com/anrivera/region-countries-states-cities-JSON#readme","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-C3OPMvITHEJoznbpTXHumgGoba8HwcDNvFfUBECLDuJfX44s0Rt1ieYMrQUBXafdzGWmn9gy+jl4ns15PtVMew==","shasum":"621e7643f46172c9ee0adb89ff1e426b98f3f071","tarball":"https://registry.npmjs.org/@anrivera/countries-states-cities-database/-/countries-states-cities-database-1.0.0.tgz","fileCount":207,"unpackedSize":43568141,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHEpgM1L3DblkNl3rr0E/oNMdYlpaHTd7RsObIBxoBSBAiEAlqnHBR3dMWQ/efoz/D/viIFPuVGLt7Widg7gSfej2co="}]},"_npmUser":{"name":"anrivera","email":"anriverax@gmail.com"},"directories":{},"maintainers":[{"name":"anrivera","email":"anriverax@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/countries-states-cities-database_1.0.0_1773869755161_0.15420319645338676"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-18T21:35:55.034Z","1.0.0":"2026-03-18T21:35:55.498Z","modified":"2026-03-18T21:35:55.749Z"},"maintainers":[{"name":"anrivera","email":"anriverax@gmail.com"}],"description":"Open dataset of countries, states and cities in JSON","homepage":"https://github.com/anrivera/region-countries-states-cities-JSON#readme","keywords":["countries","states","cities","regions","subregions","json","database","geography"],"repository":{"type":"git","url":"git+https://github.com/anrivera/region-countries-states-cities-JSON.git"},"bugs":{"url":"https://github.com/anrivera/region-countries-states-cities-JSON/issues"},"license":"MIT","readme":"# 🌍 Countries States Cities Database\r\n\r\n[![npm](https://img.shields.io/npm/v/countries-states-cities-database)](https://www.npmjs.com/package/countries-states-cities-database)\r\n[![npm downloads](https://img.shields.io/npm/dm/countries-states-cities-database)](https://www.npmjs.com/package/countries-states-cities-database)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\r\n\r\nAn open-source dataset containing countries, states, and cities in JSON format.\r\n\r\n**Includes:**\r\n- ✔ 250+ countries\r\n- ✔ 5000+ states\r\n- ✔ 150k+ cities\r\n- ✔ ISO codes (ISO2, ISO3, numeric)\r\n- ✔ Latitude and longitude\r\n- ✔ Regions and subregions\r\n- ✔ Timezones\r\n- ✔ Phone / dial codes\r\n- ✔ Emoji flags\r\n\r\n---\r\n\r\n## 📁 Repository Structure\r\n\r\n```\r\ncountries-states-cities-database\r\n│\r\n├── index.js              — Main entry point with helper functions\r\n│\r\n├── data\r\n│   ├── countries.json    — All countries with ISO codes, phone codes, timezones, flags …\r\n│   ├── regions.json      — World regions (Africa, Americas, Asia, Europe, Oceania …)\r\n│   ├── subregions.json   — Sub-regions linked to regions\r\n│   ├── states.json       — States / provinces / territories per country\r\n│   ├── cities.json       — Cities per state (full flat file)\r\n│   ├── languages.json    — Language list with ISO codes\r\n│   └── cities/           — Per-country city files (split from cities.json)\r\n│       ├── SV.json       — Cities in El Salvador\r\n│       ├── US.json       — Cities in the United States\r\n│       ├── MX.json       — Cities in Mexico\r\n│       └── …             — One file per country (ISO2 code)\r\n│\r\n├── types\r\n│   ├── index.d.ts        — TypeScript function declarations\r\n│   ├── country.d.ts      — TypeScript interface for a Country record\r\n│   ├── state.d.ts        — TypeScript interface for a State record\r\n│   └── city.d.ts         — TypeScript interface for a City record\r\n│\r\n├── scripts\r\n│   ├── validate-data.js  — Node.js script to validate all data files\r\n│   └── split-cities.js   — Script to (re)generate data/cities/ from data/cities.json\r\n│\r\n├── demo\r\n│   └── index.html        — Browser demo (country → state → cities)\r\n│\r\n├── README.md\r\n└── LICENSE\r\n```\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\n### Install\r\n\r\n```bash\r\nnpm install countries-states-cities-database\r\n```\r\n\r\n### Use the helper API (recommended)\r\n\r\n```js\r\nconst {\r\n  // Data accessors\r\n  getCountries,\r\n  getStates,\r\n  getRegions,\r\n  getSubregions,\r\n  getLanguages,\r\n  // Country lookups\r\n  getCountriesByLanguage,\r\n  getCountryById,\r\n  getCountryByIso2,\r\n  getCountryByIso3,\r\n  // State lookups\r\n  getStateByCode,\r\n  getStatesOfCountry,\r\n  getStatesOfCountryById,\r\n  // City lookups\r\n  getCitiesOfCountry,\r\n  getCitiesOfState,\r\n  searchCity,\r\n  // Geo calculations\r\n  calculateDistance,\r\n  getNearestCities,\r\n} = require('countries-states-cities-database');\r\n```\r\n\r\n---\r\n\r\n## 📘 API Reference\r\n\r\n### Data Accessors\r\n\r\n#### `getCountries()`\r\n\r\nReturns the full list of all countries.\r\n\r\n```js\r\nconst countries = getCountries();\r\n// [\r\n//   { id, name, iso2, iso3, numericCode, phoneCode, capital, tld,\r\n//     timezones, latlng, emoji, languages, flag, flags, maps, coatOfArms },\r\n//   …\r\n// ]\r\nconsole.log(countries.length); // 249\r\n```\r\n\r\n#### `getStates()`\r\n\r\nReturns the full list of states / provinces / territories.\r\n\r\n```js\r\nconst states = getStates();\r\n// [{ id, name, countryId, stateCode, latitude, longitude }, …]\r\nconsole.log(states.length); // ~5000\r\n```\r\n\r\n#### `getRegions()`\r\n\r\nReturns the 8 world regions.\r\n\r\n```js\r\nconst regions = getRegions();\r\n// [{ id: 1, name: \"Africa\" }, { id: 2, name: \"Americas\" }, …]\r\n```\r\n\r\n#### `getSubregions()`\r\n\r\nReturns all sub-regions, each linked to a region via `regionId`.\r\n\r\n```js\r\nconst subregions = getSubregions();\r\n// [{ id, regionId, name }, …]\r\n```\r\n\r\n#### `getLanguages()`\r\n\r\nReturns all supported languages with their ISO 639-1 codes.\r\n\r\n```js\r\nconst languages = getLanguages();\r\n// [{ name: \"English\", iso: \"en\" }, { name: \"Spanish\", iso: \"es\" }, …]\r\n```\r\n\r\n---\r\n\r\n### Country Lookups\r\n\r\n#### `getCountryByIso2(iso2)`\r\n\r\nReturns the country matching the given ISO 3166-1 **alpha-2** code, or `null` if not found.\r\n\r\n```js\r\nconst country = getCountryByIso2('SV');\r\n// {\r\n//   id: 65,\r\n//   name: \"El Salvador\",\r\n//   iso2: \"SV\",\r\n//   iso3: \"SLV\",\r\n//   phoneCode: \"+503\",\r\n//   capital: \"San Salvador\",\r\n//   timezones: { zoneName: \"America/El_Salvador\", … },\r\n//   latlng: [\"13.83333333\", \"-88.91666666\"],\r\n//   …\r\n// }\r\n\r\ngetCountryByIso2('xx'); // null\r\n```\r\n\r\n#### `getCountryByIso3(iso3)`\r\n\r\nReturns the country matching the given ISO 3166-1 **alpha-3** code, or `null` if not found.\r\n\r\n```js\r\nconst country = getCountryByIso3('SLV');\r\n// { id: 65, name: \"El Salvador\", iso2: \"SV\", iso3: \"SLV\", … }\r\n\r\nconst us = getCountryByIso3('USA');\r\n// { id: 235, name: \"United States\", iso2: \"US\", iso3: \"USA\", … }\r\n\r\ngetCountryByIso3('XXX'); // null\r\n```\r\n\r\n#### `getCountryById(id)`\r\n\r\nReturns the country matching the given numeric ID, or `null` if not found.\r\n\r\n```js\r\nconst country = getCountryById(235);\r\n// { id: 235, name: \"United States\", iso2: \"US\", iso3: \"USA\", … }\r\n\r\ngetCountryById(9999); // null\r\n```\r\n\r\n#### `getCountriesByLanguage(languageIso)`\r\n\r\nReturns all countries where the given language is spoken.  Countries that do not\r\nlist the language are excluded from the result.\r\n\r\nThe function accepts:\r\n- An **ISO 639-3** three-letter code (e.g. `\"eng\"`, `\"spa\"`) — as stored in the\r\n  `languages` field of each country record.\r\n- An **ISO 639-1** two-letter code (e.g. `\"en\"`, `\"es\"`) — as stored in\r\n  `data/languages.json`.\r\n- A **language name** (e.g. `\"English\"`, `\"Spanish\"`) — matched\r\n  case-insensitively.\r\n\r\n```js\r\n// By ISO 639-3 code (as stored in country records)\r\nconst englishCountries = getCountriesByLanguage('eng');\r\n// [{ id, name: \"United States\", … }, { id, name: \"United Kingdom\", … }, …]\r\n\r\n// By ISO 639-1 code (as in languages.json)\r\nconst spanishCountries = getCountriesByLanguage('es');\r\n// All countries where Spanish is spoken\r\n\r\n// By language name\r\nconst frenchCountries = getCountriesByLanguage('French');\r\n```\r\n\r\n---\r\n\r\n### State Lookups\r\n\r\n#### `getStateByCode(code)`\r\n\r\nReturns the state matching the given combined `\"<countryIso2>-<stateCode>\"` code, or `null` if not found.\r\n\r\n```js\r\nconst state = getStateByCode('US-CA');\r\n// { id: 1416, name: \"California\", countryId: 235, stateCode: \"CA\",\r\n//   latitude: \"36.77826100\", longitude: \"-119.41793200\" }\r\n\r\nconst jalisco = getStateByCode('MX-JAL');\r\n// { id, name: \"Jalisco\", countryId, stateCode: \"JAL\", latitude, longitude }\r\n```\r\n\r\n#### `getStatesOfCountry(iso2)`\r\n\r\nReturns all states/provinces for a given country ISO2 code.\r\n\r\n```js\r\nconst states = getStatesOfCountry('US');\r\n// [{ id, name, countryId, stateCode, latitude, longitude }, …]  (~50 entries)\r\n\r\nconst svStates = getStatesOfCountry('SV');\r\n// All departments of El Salvador\r\n```\r\n\r\n#### `getStatesOfCountryById(countryId)`\r\n\r\nReturns all states/provinces for a given numeric country ID.\r\n\r\n```js\r\nconst states = getStatesOfCountryById(101);\r\n// [{ id, name, countryId, stateCode, latitude, longitude }, …]\r\n```\r\n\r\n#### `getCitiesOfCountry(iso2)`\r\n\r\nReturns all cities for a given country ISO2 code (loaded from the per-country file — lightweight).\r\n\r\n```js\r\nconst cities = getCitiesOfCountry('SV');\r\n// [{ id, name, stateId, latitude, longitude }, …]\r\n\r\nconst mxCities = getCitiesOfCountry('MX');\r\n// ~4,000 cities in Mexico\r\n```\r\n\r\n#### `getCitiesOfState(stateId)`\r\n\r\nReturns all cities/municipalities that belong to a given state, identified by its numeric ID.\r\n\r\n```js\r\n// First get the state to know its id\r\nconst state = getStateByCode('US-CA'); // { id: 681, … }\r\nconst cities = getCitiesOfState(681);\r\n// [{ id, name, stateId, latitude, longitude }, …]\r\n```\r\n\r\n#### `searchCity(query)`\r\n\r\nFast city search — returns all cities whose name contains the query string (case-insensitive).\r\nThe city index is built once on the first call and cached in memory.\r\n\r\n```js\r\nconst results = searchCity('san');\r\n// Each result includes a `countryIso2` field:\r\n// [{ id, name, stateId, latitude, longitude, countryIso2 }, …]\r\n\r\nconst nyc = searchCity('new york');\r\n// [{ id, name: \"New York City\", stateId, latitude, longitude, countryIso2: \"US\" }]\r\n```\r\n\r\n---\r\n\r\n### Geo Calculations\r\n\r\n#### `calculateDistance(pointA, pointB)`\r\n\r\nCalculates the great-circle distance in **kilometers** between two geographic points using the **Haversine formula**.\r\n\r\nBoth arguments must be objects with `latitude` and `longitude` fields (strings or numbers),\r\nwhich matches the shape of city and state objects in this dataset.\r\n\r\n```js\r\nconst sanSalvador = { latitude: \"13.6929\", longitude: \"-89.2182\" };\r\nconst guatemalaCity = { latitude: \"14.6349\", longitude: \"-90.5069\" };\r\n\r\nconst km = calculateDistance(sanSalvador, guatemalaCity);\r\n// 174\r\n\r\n// Works directly with city/state objects from the dataset:\r\nconst cities = getCitiesOfCountry('SV');\r\nconst [cityA, cityB] = cities;\r\nconst dist = calculateDistance(cityA, cityB);\r\n```\r\n\r\n#### `getNearestCities(lat, lng, limit?, iso2?)`\r\n\r\nReturns the **N nearest cities** to a given geographic point, sorted by distance ascending.\r\nEach result is augmented with a `distance` field (km) and a `countryIso2` field.\r\n\r\n| Parameter | Type | Default | Description |\r\n|-----------|------|---------|-------------|\r\n| `lat` | `number` | — | Latitude of the reference point |\r\n| `lng` | `number` | — | Longitude of the reference point |\r\n| `limit` | `number` | `5` | Maximum number of results |\r\n| `iso2` | `string` | — | Optional ISO2 code to restrict search to one country |\r\n\r\n```js\r\n// 3 nearest cities to San Salvador (globally)\r\nconst nearest = getNearestCities(13.6929, -89.2182, 3);\r\n// [\r\n//   { id, name: \"San Salvador\",       …, countryIso2: \"SV\", distance: 3.37 },\r\n//   { id, name: \"Antiguo Cuscatlán\",  …, countryIso2: \"SV\", distance: 4.9  },\r\n//   { id, name: \"Mejicanos\",          …, countryIso2: \"SV\", distance: 5.3  },\r\n// ]\r\n\r\n// Restrict search to El Salvador (faster — avoids loading all cities)\r\nconst svNearest = getNearestCities(13.6929, -89.2182, 5, 'SV');\r\n```\r\n\r\n---\r\n\r\n## 🗂️ Data Properties\r\n\r\n### Country properties\r\n\r\nEach country object has the following properties:\r\n\r\n| Property | Type | Example |\r\n|----------|------|---------|\r\n| `id` | `number` | `65` |\r\n| `name` | `string` | `\"El Salvador\"` |\r\n| `iso2` | `string` | `\"SV\"` |\r\n| `iso3` | `string` | `\"SLV\"` |\r\n| `numericCode` | `string` | `\"222\"` |\r\n| `phoneCode` | `string` | `\"+503\"` |\r\n| `capital` | `string` | `\"San Salvador\"` |\r\n| `tld` | `string` | `\".sv\"` |\r\n| `timezones` | `object` | `{ zoneName: \"America/El_Salvador\", … }` |\r\n| `latlng` | `[string, string]` | `[\"13.83\", \"-88.91\"]` |\r\n| `emoji` | `[string, string]` | `[\"🇸🇻\", \"U+1F1F8 U+1F1FB\"]` |\r\n| `languages` | `object` | `{ \"spa\": \"Spanish\" }` |\r\n| `flag` | `string` | `\"🇸🇻\"` |\r\n| `flags` | `object` | `{ png: \"…\", svg: \"…\" }` |\r\n| `maps` | `object` | `{ googleMaps: \"…\", openStreetMaps: \"…\" }` |\r\n| `coatOfArms` | `object` | `{ png: \"…\", svg: \"…\" }` |\r\n| `currency` | `string` | `\"USD\"` *(optional — when present)* |\r\n| `translations` | `object` | `{ \"es\": \"El Salvador\", \"fr\": \"Le Salvador\" }` *(optional — when present)* |\r\n\r\n#### 🌍 Timezones\r\n\r\n```json\r\n{\r\n  \"name\": \"El Salvador\",\r\n  \"timezones\": {\r\n    \"zoneName\": \"America/El_Salvador\",\r\n    \"gmtOffset\": -21600,\r\n    \"gmtOffsetName\": \"UTC-06:00\",\r\n    \"abbreviation\": \"CST\",\r\n    \"tzName\": \"Central Standard Time (North America)\"\r\n  }\r\n}\r\n```\r\n\r\n#### 💰 Currency *(optional field)*\r\n\r\n```json\r\n{\r\n  \"name\": \"El Salvador\",\r\n  \"currency\": \"USD\"\r\n}\r\n```\r\n\r\n#### 📞 Phone code\r\n\r\n```json\r\n{\r\n  \"name\": \"El Salvador\",\r\n  \"phoneCode\": \"+503\"\r\n}\r\n```\r\n\r\n#### 🌐 Translations *(optional field)*\r\n\r\nCountry names can optionally include translations keyed by ISO 639-1 language code:\r\n\r\n```json\r\n{\r\n  \"name\": \"Germany\",\r\n  \"translations\": {\r\n    \"es\": \"Alemania\",\r\n    \"fr\": \"Allemagne\",\r\n    \"pt\": \"Alemanha\",\r\n    \"de\": \"Deutschland\"\r\n  }\r\n}\r\n```\r\n\r\n### State properties\r\n\r\n| Property | Type | Example |\r\n|----------|------|---------|\r\n| `id` | `number` | `1416` |\r\n| `name` | `string` | `\"California\"` |\r\n| `countryId` | `number` | `235` |\r\n| `stateCode` | `string` | `\"CA\"` |\r\n| `latitude` | `string` | `\"36.77826100\"` |\r\n| `longitude` | `string` | `\"-119.41793200\"` |\r\n\r\n### City properties\r\n\r\n| Property | Type | Example |\r\n|----------|------|---------|\r\n| `id` | `number` | `131` |\r\n| `name` | `string` | `\"Abbeville\"` |\r\n| `stateId` | `number` | `113` |\r\n| `latitude` | `string` | `\"31.57184000\"` |\r\n| `longitude` | `string` | `\"-85.25049000\"` |\r\n\r\n---\r\n\r\n## 📦 Data Files\r\n\r\n| File | Description | Records |\r\n|---|---|---|\r\n| `data/countries.json` | Countries with ISO2/ISO3, phone code, capital, TLD, timezones, coordinates, emoji flag, languages | 250 |\r\n| `data/regions.json` | World regions | 8 |\r\n| `data/subregions.json` | Sub-regions linked to a region | 27 |\r\n| `data/states.json` | States / provinces / territories | 5,000 + |\r\n| `data/cities.json` | Cities with coordinates (full flat file) | 150,000 + |\r\n| `data/cities/{ISO2}.json` | Per-country city files — one file per country | 150,000 + total |\r\n| `data/languages.json` | Languages with ISO codes | 23 |\r\n\r\n### Use the data directly\r\n\r\n```js\r\nconst countries = require('./data/countries.json');\r\nconst states    = require('./data/states.json');\r\nconst cities    = require('./data/cities.json');\r\n\r\n// Per-country cities (lightweight – loads only one country at a time)\r\nconst svCities = require('./data/cities/SV.json');\r\n```\r\n\r\n---\r\n\r\n## 🛠 Scripts\r\n\r\n### Run the demo\r\n\r\nServe the repository root with any static server, e.g.:\r\n\r\n```bash\r\nnpx serve .\r\n# then open http://localhost:3000/demo/index.html\r\n```\r\n\r\n### Validate data files\r\n\r\n```bash\r\nnpm run validate\r\n```\r\n\r\n### Re-generate per-country city files\r\n\r\n```bash\r\nnpm run split-cities\r\n```\r\n\r\n---\r\n\r\n## 🌐 Language Support\r\n\r\nThe **names** of countries, states and cities in this database are provided in **English only**.\r\nFull multilingual translation of 150 000+ place names is outside the scope of this dataset.\r\n\r\nWhat the package **does** include is language *metadata*:\r\n\r\n- `data/languages.json` - list of 23 languages with ISO 639-1 codes (`en`, `es`, `fr`, ...)\r\n- Each country record includes a `languages` field that maps ISO 639-3 codes to language names\r\n  spoken in that country.\r\n\r\n```js\r\nconst { getLanguages, getCountryByIso2, getCountriesByLanguage } = require('countries-states-cities-database');\r\n\r\n// List all supported language codes\r\nconst langs = getLanguages();\r\n// [{ name: \"English\", iso: \"en\" }, { name: \"Spanish\", iso: \"es\" }, …]\r\n\r\n// Languages spoken in Mexico\r\nconst mx = getCountryByIso2('MX');\r\nconsole.log(mx.languages);\r\n// { spa: \"Spanish\" }\r\n\r\n// All English-speaking countries (~91 countries)\r\nconst englishSpeaking = getCountriesByLanguage('eng');  // by ISO 639-3\r\n// or: getCountriesByLanguage('en')                     // by ISO 639-1\r\n// or: getCountriesByLanguage('English')                // by name\r\nconsole.log(englishSpeaking.map(c => c.name));\r\n// [\"American Samoa\", \"Anguilla\", \"Australia\", \"Belize\", \"Canada\", \"United States\", …]\r\n```\r\n\r\nIf your application needs localised place names, you can use the `id` / `iso2` / `iso3` fields\r\nfrom this dataset as keys to look up translations in a third-party i18n library or your own\r\ntranslation files.\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nPull requests are welcome! Please open an issue first for major changes.\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\n[MIT](LICENSE)","readmeFilename":"README.md","_rev":"1-6d8983d04146a156c9cf1e05a7e34d17"}