![](\"https://github.com/Cyber-Squad-Inc/assets/blob/main/logo.png\"){kind=logo}
\n\n \n
\n Complete offline world dataset with countries, states, and cities — maintained by Cyber Squad Inc.\n
\n\n\n\n## ✨ Features\n\n- **249 countries** with complete data\n- **States/Provinces** for each country\n- **Cities** with coordinates and population data\n- **ISO codes** (ISO2, ISO3, numeric)\n- **Phone codes** and **timezones**\n- **Flags** (rectangular and round)\n- **Currencies** and **languages**\n- **Regions** and **subregions**\n- **Districts** and **suburbs** (where available)\n- **Zero dependencies** for runtime usage\n- **Offline-first** - no API calls needed\n\n## 📦 Install\n\n```bash\nnpm install @cyber_squad_inc/world-locations\n```\n\n## 🚀 Usage\n\n### Basic Usage\n\n```javascript\nimport { getCountries, getCountry, getStates, getCities } from '@cyber_squad_inc/world-locations';\n\n// Get all countries (lightweight list)\nconst countries = getCountries();\nconsole.log(countries);\n// [\n// {\n// name: \"United States\",\n// officialName: \"United States of America\",\n// iso2: \"US\",\n// iso3: \"USA\",\n// phoneCode: \"1\",\n// flag: \"https://flagcdn.com/w320/us.png\",\n// capital: \"Washington, D.C.\",\n// region: \"Americas\",\n// subregion: \"North America\",\n// // ... more fields\n// },\n// // ... 248 more countries\n// ]\n\n// Get full country data\nconst usa = getCountry('US');\nconsole.log(usa.name.common); // \"United States\"\nconsole.log(usa.states.length); // 50+ states\n\n// Get states for a country\nconst states = getStates('BD');\nconsole.log(states);\n// [\n// { name: \"Dhaka\", code: \"13\", cities: [...] },\n// { name: \"Chittagong\", code: \"10\", cities: [...] },\n// // ... more states\n// ]\n\n// Get cities for a specific state\nconst cities = getCities('BD', 'Dhaka');\nconsole.log(cities);\n// [\n// { name: \"Dhaka\", latlng: [23.8103, 90.4125], population: 10356500 },\n// { name: \"Gazipur\", latlng: [24.0023, 90.4264], population: 1200000 },\n// // ... more cities\n// ]\n```\n\n### Advanced Usage\n\n```javascript\nimport { \n searchCountries, \n getCountriesByRegion, \n getCountriesBySubregion \n} from '@cyber_squad_inc/world-locations';\n\n// Search countries by name\nconst results = searchCountries('united');\nconsole.log(results);\n// [\n// { name: \"United States\", iso2: \"US\", ... },\n// { name: \"United Kingdom\", iso2: \"GB\", ... },\n// { name: \"United Arab Emirates\", iso2: \"AE\", ... }\n// ]\n\n// Get countries by region\nconst europeanCountries = getCountriesByRegion('Europe');\nconsole.log(europeanCountries.length); // 50+ countries\n\n// Get countries by subregion\nconst scandinavianCountries = getCountriesBySubregion('Northern Europe');\nconsole.log(scandinavianCountries);\n// [\n// { name: \"Denmark\", iso2: \"DK\", ... },\n// { name: \"Finland\", iso2: \"FI\", ... },\n// { name: \"Iceland\", iso2: \"IS\", ... },\n// { name: \"Norway\", iso2: \"NO\", ... },\n// { name: \"Sweden\", iso2: \"SE\", ... }\n// ]\n```\n\n### Default Import\n\n```javascript\nimport worldLocations from '@cyber_squad_inc/world-locations';\n\nconst countries = worldLocations.getCountries();\nconst usa = worldLocations.getCountry('US');\nconst states = worldLocations.getStates('US');\nconst cities = worldLocations.getCities('US', 'California');\n```\n\n## 📊 Data Structure\n\n### Country Object\n```typescript\ninterface Country {\n name: {\n common: string;\n official: string;\n };\n iso2: string;\n iso3: string;\n numericCode: string;\n region: string;\n subregion: string;\n tld: string;\n phoneCode: string;\n capital: string;\n currencies: Record![\"npm](\"https://img.shields.io/npm/v/@cyber_squad_inc/world-locations.svg?style=flat-square\")
\n ![\"GitHub](\"https://img.shields.io/github/stars/Cyber-Squad-Inc/world-locations.svg?style=flat-square\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square\"){kind=icon}
\n