Why I Built a New NPM Package for Accurate Country, State, and District Data

Abi thanush — Sun, 09 Aug 2026 14:19:39 +0000

Geographic dropdowns (Country ➔ State ➔ District) are a standard feature in almost every web application.

Most developers turn to popular libraries like country-state-city (which has over 15k stars) to get this data. However, while working on a recent project, I realized how inaccurate and bloated existing solutions are.

The Problem: Sri Lanka Has 9 Provinces, Not 15+

In popular libraries, when you query subdivisions for Sri Lanka, it returns 15+ random entities that are mixtures of old boundaries and local municipalities instead of the official 9 provinces.

This inaccuracy is common across many countries. On top of that, these packages load massive 8MB+ JSON databases into memory at once, which slows down client-side applications.

To solve this, I built and published: world-country-state-district.

What Makes This Package Different?

1. Verified Administrative Accuracy

I verified the data against official government directories.

Sri Lanka: Exactly 9 provinces and 25 districts.
India: Exactly 28 states, 8 Union Territories, and 780 districts.
Every data file has passed structural checks and contains source links.

2. On-Demand Lazy Loading (Under 68kB unpacked!)

Instead of loading all countries at once, this library loads country data files dynamically. Calling getSubdivisions('LK') reads only the tiny 2KB LK.json file and caches it. The rest of the world data remains untouched on disk.

3. Flexible Hierarchy

It respects that different countries have different admin levels rather than forcing a standard State ➔ City model:

Sri Lanka: Province ➔ District
India: State ➔ District
UK: Country ➔ County/Area

Quick Start

You can install it in any Node.js project:


bash
npm install world-country-state-district

const geo = require('world-country-state-district');

// Get provinces
const provinces = geo.getSubdivisions('LK');

// Get districts inside Western Province
const districts = geo.getSubdivisionChildren('LK', 'Western Province');



![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/3kftahg42u05sgtknqc5.png)The package is fully open-source and ready to use:

📦 NPM Registry: world-country-state-district
💻 GitHub Repo: abiA2711/world-country-state-district