@deviabirami/country-state-district

Accurate, ISO 3166 compliant geographic data — Country → State/Province → District — verified against official government sources.

Why This Package?

Existing npm packages for geographic data (country-state-city, etc.) suffer from:

• ❌ Inaccurate data — Sri Lanka shows 15+ "states" instead of exactly 9 provinces
• ❌ Massive bundles — 8MB+ JSON files crashing browsers
• ❌ Generic structure — forcing a 3-tier model on every country
• ❌ Unmaintained — data corrections sit unmerged for years

This package fixes all of that:

• ✅ Verified data — every country matches its official administrative structure
• ✅ ISO 3166-2 codes — proper international standard codes for every subdivision
• ✅ Lightweight — on-demand loading, each country file is 1-10KB
• ✅ Flexible hierarchy — respects each country's real admin levels (province → district, state → district, division → district, etc.)
• ✅ Source-linked — every data file references official government sources

Installation

npm install @deviabirami/country-state-district

Quick Start

const {
  getCountries,
  getCountryByCode,
  getSubdivisions,
  getSubdivisionChildren,
  searchSubdivisions
} = require('country-state-district');

// Get all countries
const countries = getCountries();
console.log(countries.length); // 199

// Get a specific country
const sriLanka = getCountryByCode('LK');
console.log(sriLanka);
// { name: 'Sri Lanka', isoCode: 'LK', iso3Code: 'LKA', flag: '🇱🇰', ... }

// Get subdivisions (provinces/states)
const provinces = getSubdivisions('LK');
console.log(provinces.length); // 9 (exactly right!)

// Get districts within a province
const districts = getSubdivisionChildren('LK', 'Western Province');
console.log(districts);
// [{ name: 'Colombo', type: 'district' }, { name: 'Gampaha', type: 'district' }, ...]

// Search for subdivisions
const results = searchSubdivisions('IN', 'Chennai');
console.log(results);
// [{ name: 'Chennai', type: 'district', path: ['Tamil Nadu', 'Chennai'] }]

API Reference

Country Functions

getCountries()

Returns an array of all countries with metadata.

const countries = getCountries();
// Returns: [{ name, isoCode, iso3Code, phoneCode, currency, flag, continent, ... }, ...]

getCountryByCode(isoCode)

Find a country by its ISO 3166-1 alpha-2 code.

getCountryByCode('IN');  // India
getCountryByCode('US');  // United States

getCountryByIso3(iso3Code)

Find a country by its ISO 3166-1 alpha-3 code.

getCountryByIso3('IND');  // India
getCountryByIso3('USA');  // United States

getCountryByName(name)

Find a country by name (case-insensitive, supports partial match).

getCountryByName('Sri Lanka');  // Exact match
getCountryByName('sri');        // Partial match → Sri Lanka

Subdivision Functions

getSubdivisions(countryCode)

Get all top-level subdivisions for a country.

getSubdivisions('LK');  // 9 provinces
getSubdivisions('IN');  // 28 states + 8 union territories
getSubdivisions('US');  // 50 states + DC + territories

getSubdivisionChildren(countryCode, subdivisionName)

Get children of a specific subdivision.

getSubdivisionChildren('LK', 'Western Province');
// → [Colombo, Gampaha, Kalutara]

getSubdivisionChildren('IN', 'Tamil Nadu');
// → [Ariyalur, Chennai, Coimbatore, ...]

getSubdivisionByName(countryCode, name)

Find any subdivision by name across all hierarchy levels.

getSubdivisionByName('LK', 'Colombo');
// → { name: 'Colombo', type: 'district' }

getAdminLevels(countryCode)

Get the administrative level names used by a country.

getAdminLevels('LK');  // ['province', 'district']
getAdminLevels('IN');  // ['state', 'district']
getAdminLevels('GB');  // ['country', 'county']
getAdminLevels('BD');  // ['division', 'district']

getAvailableCountries()

Get list of country codes that have detailed subdivision data.

getAvailableCountries();
// ['AU', 'BD', 'CA', 'GB', 'IN', 'LK', 'PK', 'US']

Search Functions

searchCountries(query)

Search countries by name, ISO code, or phone code.

searchCountries('india');  // Finds India
searchCountries('LK');     // Finds Sri Lanka
searchCountries('+91');    // Finds India

searchSubdivisions(countryCode, query)

Search subdivisions within a country (searches all levels).

searchSubdivisions('IN', 'Mumbai');
// [{ name: 'Mumbai City', type: 'district', path: ['Maharashtra', 'Mumbai City'] }]

search(query, options)

Global search across countries and subdivisions.

search('Lanka');
// { countries: [Sri Lanka], subdivisions: [] }

search('Colombo', { includeSubdivisions: true, countryCode: 'LK' });
// { countries: [], subdivisions: [{ name: 'Colombo', ... }] }

Available Country Data

The package includes subdivision data for 198 countries with their ISO 3166-2 subdivisions (states, provinces, regions, autonomous communities, etc.).

For the following 8 core countries, we also provide detailed multi-level district/county hierarchies:

| Country | Code | Admin Levels | Subdivisions / Districts | |---------|------|-------------|-------------------------| | 🇱🇰 Sri Lanka | LK | Province → District | 9 provinces, 25 districts | | 🇮🇳 India | IN | State → District | 28 states + 8 UTs, 780 districts | | 🇺🇸 United States | US | State | 50 states + DC + 5 territories | | 🇬🇧 United Kingdom | GB | Country → County/Area | 4 countries, 113 subdivisions | | 🇦🇺 Australia | AU | State | 6 states + 2 territories | | 🇨🇦 Canada | CA | Province | 10 provinces + 3 territories | | 🇵🇰 Pakistan | PK | Province → District | 7 regions, 151 districts | | 🇧🇩 Bangladesh | BD | Division → District | 8 divisions, 65 districts |

For the other 190 countries, we provide complete, deduplicated state/province levels.

Data Structure

Each country data file follows this structure:

{
  "isoCode": "LK",
  "name": "Sri Lanka",
  "adminLevels": ["province", "district"],
  "source": "https://www.gov.lk",
  "subdivisions": [
    {
      "isoCode": "LK-1",
      "name": "Western Province",
      "type": "province",
      "children": [
        { "name": "Colombo", "type": "district" }
      ]
    }
  ]
}

Contributing

We welcome contributions! To add or correct data:

1. Fork the repository
2. Edit/create the JSON data file in src/data/
3. Add tests to verify accuracy
4. Run npm test and npm run validate
5. Submit a PR with sources

Adding a New Country

1. Create src/data/{ISO_CODE}.json following the structure above
2. Update hasSubdivisionData: true for the country in src/data/countries.json
3. Add tests in tests/
4. Include official government source links

License

MIT