{"id":23678996,"url":"https://github.com/d3oxy/country-state-data","last_synced_at":"2026-01-24T06:40:17.337Z","repository":{"id":267603786,"uuid":"901770190","full_name":"D3OXY/country-state-data","owner":"D3OXY","description":"A comprehensive JSON dataset containing countries, states, cities, regions, and languages with TypeScript support. Perfect for building location-based dropdowns, address forms, and geographical applications.","archived":false,"fork":false,"pushed_at":"2025-08-18T16:21:51.000Z","size":3503,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-21T01:29:22.592Z","etag":null,"topics":["address","cities","countries","currency","data","dropdown","geographical","iso","json","languages","location","regions","states","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/country-state-data","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/D3OXY.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-11T09:31:00.000Z","updated_at":"2025-09-13T16:37:01.000Z","dependencies_parsed_at":"2024-12-11T10:41:35.660Z","dependency_job_id":null,"html_url":"https://github.com/D3OXY/country-state-data","commit_stats":null,"previous_names":["d3oxy/country-state-data"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/D3OXY/country-state-data","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/D3OXY%2Fcountry-state-data","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/D3OXY%2Fcountry-state-data/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/D3OXY%2Fcountry-state-data/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/D3OXY%2Fcountry-state-data/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/D3OXY","download_url":"https://codeload.github.com/D3OXY/country-state-data/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/D3OXY%2Fcountry-state-data/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28716845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T05:53:42.649Z","status":"ssl_error","status_checked_at":"2026-01-24T05:53:41.698Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["address","cities","countries","currency","data","dropdown","geographical","iso","json","languages","location","regions","states","typescript"],"created_at":"2024-12-29T16:59:49.260Z","updated_at":"2026-01-24T06:40:17.331Z","avatar_url":"https://github.com/D3OXY.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Country State Data\n\nA comprehensive JSON dataset containing a hierarchical list of countries, states, cities, regions, and languages. This repository provides structured geographical and linguistic data that can be easily integrated into applications requiring location-based functionality.\n\n## Features\n\n- Complete list of countries with ISO codes, currencies, timezones, and translations\n- States/provinces/regions for each country\n- Cities data organized by states and countries\n- Regional classifications\n- Language data with native names\n- TypeScript definitions included\n- Multiple file formats (full and minified versions)\n- Well-structured JSON format\n- Easy to integrate\n- Regularly maintained and verified data\n\n## Installation\n\n### PNPM (Recommended)\n```bash\npnpm add country-state-data\n```\n\n### NPM\n```bash\nnpm install country-state-data\n```\n\n### Direct Download\nDownload the JSON files directly from this repository for local use.\n\n## Quick Start\n\n### Using the main API (Recommended)\n```javascript\n// Install the package\npnpm add country-state-data\n\n// Import the main API\nimport countryStateData from 'country-state-data';\n\n// Get all countries\nconst countries = countryStateData.getAllCountries();\nconsole.log(countries.length); // 250 countries\n\n// Find USA by code\nconst usa = countryStateData.getCountryByCode('US');\nconsole.log(usa.name); // \"United States\"\n\n// Get US states\nconst usStates = countryStateData.getStatesByCountry('US');\nconsole.log(usStates.length); // 50+ states/territories\n\n// Search for countries\nconst searchResults = countryStateData.searchCountries('united');\nconsole.log(searchResults); // Returns USA, UAE, UK\n\n// Validate country code\nconst isValid = countryStateData.isValidCountryCode('US'); // true\n\n// Get country flag emoji\nconst flag = countryStateData.getCountryFlag('JP'); // 🇯🇵\n```\n\n### Direct JSON import (Alternative)\n```javascript\nimport countries from 'country-state-data/countries';\nimport states from 'country-state-data/states';\n\n// Direct access to raw data\nconst usa = countries.find(c =\u003e c.iso2 === 'US');\nconst usStates = states.filter(s =\u003e s.country_code === 'US');\n```\n\n## Available Data Files\n\n| File | Description | Size |\n|------|-------------|------|\n| `countries.json` | Complete country data | ~119KB |\n| `states.json` | Complete state/province data | ~605KB |\n| `cities.json` | Cities organized by country and state | ~35MB |\n| `regions.json` | World regions data | ~419B |\n| `languages.json` | World languages with native names | ~15KB |\n| `types.d.ts` | TypeScript definitions | Included |\n\n## Data Structure\n\n### Countries (`countries.json`)\n```json\n{\n  \"id\": 1,\n  \"name\": \"Afghanistan\",\n  \"iso3\": \"AFG\",\n  \"iso2\": \"AF\",\n  \"phone_code\": \"93\",\n  \"capital\": \"Kabul\",\n  \"currency\": \"AFN\",\n  \"currency_symbol\": \"؋\",\n  \"native\": \"افغانستان\",\n  \"region\": \"Asia\",\n  \"subregion\": \"Southern Asia\",\n  \"latitude\": \"33.00000000\",\n  \"longitude\": \"65.00000000\",\n  \"emoji\": \"🇦🇫\"\n}\n```\n\n### States (`states.json`)\n```json\n{\n  \"id\": 3901,\n  \"name\": \"Badakhshan\",\n  \"country_id\": 1,\n  \"country_code\": \"AF\",\n  \"country_name\": \"Afghanistan\",\n  \"state_code\": \"BDS\",\n  \"latitude\": \"36.73477250\",\n  \"longitude\": \"70.81199530\"\n}\n```\n\n### Cities (`cities.json`)\n```json\n{\n  \"id\": 1,\n  \"states\": [\n    {\n      \"id\": 3901,\n      \"cities\": [\n        {\n          \"id\": 52,\n          \"name\": \"Ashkāsham\",\n          \"latitude\": \"36.68333000\",\n          \"longitude\": \"71.53333000\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### Regions (`regions.json`)\n```json\n{\n  \"id\": \"111\",\n  \"name\": \"Asia\",\n  \"hasCountries\": true\n}\n```\n\n### Languages (`languages.json`)\n```json\n{\n  \"code\": \"en\",\n  \"name\": \"English\",\n  \"native\": \"English\"\n}\n```\n\n## API Documentation\n\n### Main API Methods\n\nThe package provides a comprehensive API through the main export:\n\n```javascript\nconst countryStateData = require('country-state-data');\n// or\nimport countryStateData from 'country-state-data';\n```\n\n#### Country Methods\n- `getAllCountries()` - Returns all countries\n- `getCountryByCode(code)` - Get country by ISO2 or ISO3 code\n- `getCountryById(id)` - Get country by numeric ID\n- `getCountriesByRegion(regionName)` - Get countries in a region\n- `getCountriesBySubregion(subregionName)` - Get countries in a subregion\n- `searchCountries(query)` - Search countries by name, native name, capital, or nationality\n- `getCountriesByCurrency(currencyCode)` - Get countries using a currency\n- `getCountriesByPhoneCode(phoneCode)` - Get countries by phone code\n\n#### State/Province Methods\n- `getAllStates()` - Returns all states/provinces\n- `getStatesByCountry(countryCode)` - Get states by country ISO code\n- `getStatesByCountryId(countryId)` - Get states by country ID\n- `getStateByCode(stateCode, countryCode)` - Get specific state\n- `searchStates(query, countryCode?)` - Search states, optionally within a country\n\n#### City Methods\n- `getCitiesByState(stateId)` - Get cities in a state\n- `getCitiesByCountry(countryCode)` - Get all cities in a country\n- `searchCities(query, countryCode?, stateId?)` - Search cities\n\n#### Region Methods\n- `getAllRegions()` - Get all regions\n- `getRegionById(regionId)` - Get region by ID\n- `getUniqueRegions()` - Get unique region names\n- `getUniqueSubregions()` - Get unique subregion names\n\n#### Language Methods\n- `getAllLanguages()` - Get all languages\n- `getLanguageByCode(code)` - Get language by ISO code\n- `searchLanguages(query)` - Search languages\n\n#### Currency Methods\n- `getAllCurrencies()` - Get all unique currencies\n- `getCurrencyByCode(currencyCode)` - Get currency details\n\n#### Timezone Methods\n- `getAllTimezones()` - Get all unique timezones\n- `getCountriesByTimezone(zoneName)` - Get countries in a timezone\n\n#### Validation Methods\n- `isValidCountryCode(code)` - Validate country code\n- `isValidStateCode(stateCode, countryCode)` - Validate state code\n- `isValidLanguageCode(code)` - Validate language code\n- `isValidCurrencyCode(code)` - Validate currency code\n\n#### Utility Methods\n- `getCountryFlag(countryCode)` - Get country flag emoji\n- `getCountryPhoneFormat(countryCode)` - Get phone format with country code\n- `getCountryInfo(countryCode)` - Get extended country info with state/city counts\n- `getStatistics()` - Get data statistics\n\n## Usage Examples\n\n### Using the Main API (Recommended)\n```javascript\nconst countryStateData = require('country-state-data');\n// or ES6: import countryStateData from 'country-state-data';\n\n// Get all countries\nconst allCountries = countryStateData.getAllCountries();\nconsole.log(`Total countries: ${allCountries.length}`);\n\n// Find USA\nconst usa = countryStateData.getCountryByCode('US');\nconsole.log(usa.name); // \"United States\"\nconsole.log(usa.capital); // \"Washington\"\nconsole.log(usa.emoji); // \"🇺🇸\"\n\n// Get US states\nconst usStates = countryStateData.getStatesByCountry('US');\nconsole.log(`US has ${usStates.length} states/territories`);\n\n// Search for cities\nconst newYorkCities = countryStateData.searchCities('New York', 'US');\nconsole.log(newYorkCities);\n\n// Get countries by region\nconst asianCountries = countryStateData.getCountriesByRegion('Asia');\nconsole.log(`Asia has ${asianCountries.length} countries`);\n\n// Currency operations\nconst usdCountries = countryStateData.getCountriesByCurrency('USD');\nconsole.log('Countries using USD:', usdCountries.map(c =\u003e c.name));\n\n// Validation\nconsole.log(countryStateData.isValidCountryCode('US')); // true\nconsole.log(countryStateData.isValidCountryCode('XX')); // false\n\n// Get statistics\nconst stats = countryStateData.getStatistics();\nconsole.log(stats);\n// {\n//   totalCountries: 250,\n//   totalStates: 5000+,\n//   totalLanguages: 180+,\n//   totalRegions: 7,\n//   totalCurrencies: 160+,\n//   totalTimezones: 400+\n// }\n```\n\n### Direct JSON Import (Alternative)\n```javascript\nconst countries = require('country-state-data/countries');\nconst states = require('country-state-data/states');\nconst cities = require('country-state-data/cities');\n\n// Direct access to raw JSON data\nconst usa = countries.find(country =\u003e country.iso2 === 'US');\nconst usStates = states.filter(state =\u003e state.country_code === 'US');\n```\n\n### JavaScript (ES6 Modules)\n```javascript\nimport countries from 'country-state-data/countries';\nimport states from 'country-state-data/states';\nimport cities from 'country-state-data/cities';\n\n// Get all countries\nconsole.log(countries);\n\n// Create a country dropdown\nfunction createCountryDropdown() {\n  const select = document.createElement('select');\n  \n  countries.forEach(country =\u003e {\n    const option = document.createElement('option');\n    option.value = country.iso2;\n    option.textContent = `${country.emoji} ${country.name}`;\n    select.appendChild(option);\n  });\n  \n  return select;\n}\n\n// Handle country selection change\nfunction onCountryChange(countryCode) {\n  const country = countries.find(c =\u003e c.iso2 === countryCode);\n  const countryStates = states.filter(s =\u003e s.country_code === countryCode);\n  \n  console.log(`Selected: ${country.name}`);\n  console.log(`States: ${countryStates.length}`);\n}\n```\n\n### TypeScript\n```typescript\nimport { Country, State, Region, Language } from 'country-state-data/types';\nimport countries from 'country-state-data/countries';\nimport states from 'country-state-data/states';\nimport regions from 'country-state-data/regions';\nimport languages from 'country-state-data/languages';\n\n// Type-safe country operations\nconst getCountryByCode = (code: string): Country | undefined =\u003e {\n  return countries.find((country: Country) =\u003e country.iso2 === code);\n};\n\n// Type-safe state operations\nconst getStatesByCountry = (countryId: number): State[] =\u003e {\n  return states.filter((state: State) =\u003e state.country_id === countryId);\n};\n\n// Get countries by region with type safety\nconst getCountriesByRegion = (regionName: string): Country[] =\u003e {\n  return countries.filter((country: Country) =\u003e country.region === regionName);\n};\n\n// React component example\ninterface CountrySelectorProps {\n  onSelect: (country: Country) =\u003e void;\n}\n\nconst CountrySelector: React.FC\u003cCountrySelectorProps\u003e = ({ onSelect }) =\u003e {\n  return (\n    \u003cselect onChange={(e) =\u003e {\n      const country = getCountryByCode(e.target.value);\n      if (country) onSelect(country);\n    }}\u003e\n      \u003coption value=\"\"\u003eSelect a country\u003c/option\u003e\n      {countries.map((country: Country) =\u003e (\n        \u003coption key={country.id} value={country.iso2}\u003e\n          {country.emoji} {country.name}\n        \u003c/option\u003e\n      ))}\n    \u003c/select\u003e\n  );\n};\n\n// Language selector component\nconst LanguageSelector: React.FC = () =\u003e {\n  return (\n    \u003cselect\u003e\n      {languages.map((language: Language) =\u003e (\n        \u003coption key={language.code} value={language.code}\u003e\n          {language.native} ({language.name})\n        \u003c/option\u003e\n      ))}\n    \u003c/select\u003e\n  );\n};\n```\n\n### Advanced Usage Examples\n\n#### Real-World Example: E-commerce Address Form\n```typescript\nimport { Country, State } from 'country-state-data/types';\nimport countries from 'country-state-data/countries';\nimport states from 'country-state-data/states';\n\nclass AddressForm {\n  private countries: Country[] = countries;\n  private states: State[] = states;\n\n  // Create cascading country/state dropdowns\n  createCountryDropdown(onCountryChange: (countryCode: string) =\u003e void) {\n    const select = document.createElement('select');\n    select.innerHTML = '\u003coption value=\"\"\u003eSelect Country\u003c/option\u003e';\n    \n    this.countries.forEach(country =\u003e {\n      const option = document.createElement('option');\n      option.value = country.iso2;\n      option.textContent = `${country.emoji} ${country.name}`;\n      select.appendChild(option);\n    });\n    \n    select.onchange = (e) =\u003e onCountryChange((e.target as HTMLSelectElement).value);\n    return select;\n  }\n\n  createStateDropdown(countryCode: string) {\n    const select = document.createElement('select');\n    select.innerHTML = '\u003coption value=\"\"\u003eSelect State\u003c/option\u003e';\n    \n    const country = this.countries.find(c =\u003e c.iso2 === countryCode);\n    if (!country) return select;\n    \n    const countryStates = this.states.filter(state =\u003e state.country_id === country.id);\n    \n    countryStates.forEach(state =\u003e {\n      const option = document.createElement('option');\n      option.value = state.state_code;\n      option.textContent = state.name;\n      select.appendChild(option);\n    });\n    \n    return select;\n  }\n\n  // Validate address data\n  validateAddress(countryCode: string, stateCode?: string): boolean {\n    const country = this.countries.find(c =\u003e c.iso2 === countryCode);\n    if (!country) return false;\n\n    if (stateCode) {\n      return this.states.some(state =\u003e \n        state.state_code === stateCode \u0026\u0026 \n        state.country_id === country.id\n      );\n    }\n    \n    return true;\n  }\n\n  // Get phone format for country\n  getPhoneFormat(countryCode: string): string {\n    const country = this.countries.find(c =\u003e c.iso2 === countryCode);\n    return country ? `+${country.phone_code}` : '';\n  }\n\n  // Get currency info for pricing\n  getCurrencyInfo(countryCode: string) {\n    const country = this.countries.find(c =\u003e c.iso2 === countryCode);\n    return country ? {\n      currency: country.currency,\n      symbol: country.currency_symbol,\n      name: country.currency_name\n    } : null;\n  }\n}\n\n// Usage example\nconst addressForm = new AddressForm();\nconst countryDropdown = addressForm.createCountryDropdown((countryCode) =\u003e {\n  const stateDropdown = addressForm.createStateDropdown(countryCode);\n  document.getElementById('state-container')?.appendChild(stateDropdown);\n  \n  // Update phone format\n  const phoneInput = document.getElementById('phone') as HTMLInputElement;\n  phoneInput.placeholder = addressForm.getPhoneFormat(countryCode) + ' XXX XXXX';\n  \n  // Update currency display\n  const currency = addressForm.getCurrencyInfo(countryCode);\n  const priceDisplay = document.getElementById('price');\n  if (priceDisplay \u0026\u0026 currency) {\n    priceDisplay.textContent = `Price: ${currency.symbol}99.99 ${currency.currency}`;\n  }\n});\n```\n\n#### Search and Filter Functionality\n```typescript\nimport { Country, State, Language } from 'country-state-data/types';\nimport countries from 'country-state-data/countries';\nimport states from 'country-state-data/states';\nimport languages from 'country-state-data/languages';\n\nclass LocationSearchService {\n  // Search countries by name or native name\n  searchCountries(query: string): Country[] {\n    const lowercaseQuery = query.toLowerCase();\n    return countries.filter(country =\u003e \n      country.name.toLowerCase().includes(lowercaseQuery) ||\n      country.native.toLowerCase().includes(lowercaseQuery) ||\n      country.iso2.toLowerCase() === lowercaseQuery ||\n      country.iso3.toLowerCase() === lowercaseQuery\n    );\n  }\n\n  // Get countries by region\n  getCountriesByRegion(region: string): Country[] {\n    return countries.filter(country =\u003e country.region === region);\n  }\n\n  // Get countries by currency\n  getCountriesByCurrency(currencyCode: string): Country[] {\n    return countries.filter(country =\u003e country.currency === currencyCode);\n  }\n\n  // Get states by country\n  getStatesByCountry(countryCode: string): State[] {\n    const country = countries.find(c =\u003e c.iso2 === countryCode);\n    if (!country) return [];\n    return states.filter(state =\u003e state.country_id === country.id);\n  }\n\n  // Search languages\n  searchLanguages(query: string): Language[] {\n    const lowercaseQuery = query.toLowerCase();\n    return languages.filter(lang =\u003e\n      lang.name.toLowerCase().includes(lowercaseQuery) ||\n      lang.native.toLowerCase().includes(lowercaseQuery) ||\n      lang.code.toLowerCase() === lowercaseQuery\n    );\n  }\n\n  // Get unique regions\n  getRegions(): string[] {\n    return [...new Set(countries.map(country =\u003e country.region))];\n  }\n\n  // Get unique currencies\n  getCurrencies(): Array\u003c{code: string, name: string, symbol: string}\u003e {\n    const currencies = new Map();\n    countries.forEach(country =\u003e {\n      if (!currencies.has(country.currency)) {\n        currencies.set(country.currency, {\n          code: country.currency,\n          name: country.currency_name,\n          symbol: country.currency_symbol\n        });\n      }\n    });\n    return Array.from(currencies.values());\n  }\n}\n\n// Usage examples\nconst searchService = new LocationSearchService();\n\n// Search for countries\nconst usaResults = searchService.searchCountries('united');\nconst japanResults = searchService.searchCountries('JP');\n\n// Filter by region\nconst europeanCountries = searchService.getCountriesByRegion('Europe');\n\n// Get USD countries\nconst usdCountries = searchService.getCountriesByCurrency('USD');\n\n// Get all regions for a dropdown\nconst regions = searchService.getRegions();\n\n// Get all currencies\nconst currencies = searchService.getCurrencies();\n```\n\n## Use Cases\n\n- **E-commerce**: Country/state selection for shipping addresses\n- **Forms**: Address validation and auto-completion\n- **Analytics**: Geographical data analysis and reporting\n- **Internationalization**: Multi-language country names\n- **Travel Apps**: Location-based services and booking\n- **Educational**: Geography learning applications\n- **Government**: Administrative division management\n- **Real Estate**: Location-based property listings\n\n## File Size Considerations\n\n- Use minified versions for production to reduce bundle size\n- Consider loading data dynamically based on user interaction\n- Implement lazy loading for large datasets like cities\n- Use compression (gzip) when serving files\n\n## TypeScript Support\n\nThis package includes comprehensive TypeScript definitions. All imports are automatically typed:\n\n```typescript\nimport { Country, State, Language } from 'country-state-data/types';\nimport countries from 'country-state-data/countries'; // Country[]\nimport states from 'country-state-data/states';       // State[]\nimport languages from 'country-state-data/languages'; // Language[]\n\n// Full type safety\nconst usa: Country = countries.find(c =\u003e c.iso2 === 'US')!;\nconst californiaStates: State[] = states.filter(s =\u003e s.country_code === 'US');\n```\n\n### Available Types\n- `Country` - Complete country information with ISO codes, currency, timezone, etc.\n- `State` - State/province information with coordinates\n- `City` - City data organized by country and state\n- `Region` - World regions\n- `Language` - Language codes with native names\n- `Timezone` - Timezone information with GMT offsets\n- `Translations` - Country name translations\n\n## Contributing\n\nContributions to keep the data accurate and up-to-date are welcome. Please submit a pull request with any corrections or updates.\n\n### Data Sources\n- ISO country codes\n- Official government sources\n- United Nations data\n- Currency and timezone databases\n\n## License\n\nThis project is open source and available under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd3oxy%2Fcountry-state-data","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd3oxy%2Fcountry-state-data","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd3oxy%2Fcountry-state-data/lists"}