@techvius/bd-geo-address

Bangladesh's administrative hierarchy — Division → Zilla (District) → Thana (Upazila) — as static data with three lookup functions. Zero runtime dependencies, works in Node.js (CommonJS and ESM) and any bundler/browser.

Scope

This package intentionally covers only Division/Zilla/Thana names and their parent-child relationships. It does not include Bangla names, postal codes, union-level data, or geocoding. If you need those, see bd-geo-address (unrelated, unscoped package with a broader feature set).

Install

npm install @techvius/bd-geo-address

Usage

import {
  getAllDivision,
  getZillaByDivisionId,
  getThanaByZillaId,
} from "@techvius/bd-geo-address";

getAllDivision();
// [
//   { id: 1, name: "Dhaka" },
//   { id: 2, name: "Barishal" },
//   { id: 3, name: "Khulna" },
//   { id: 4, name: "Sylhet" },
//   { id: 5, name: "Mymensingh" },
//   { id: 6, name: "Chittagong" },
//   { id: 7, name: "Rajshahi" },
//   { id: 8, name: "Rangpur" },
// ]

getZillaByDivisionId(1); // Dhaka's zillas
// [
//   { id: 1, name: "Narshingdi", division_id: 1 },
//   { id: 2, name: "Narayanganj", division_id: 1 },
//   { id: 4, name: "Gazipur", division_id: 1 },
//   ...
// ]

getThanaByZillaId(1); // Narshingdi's thanas
// [
//   { id: 1, name: "Narshingdi Sadar", zilla_id: 1 },
//   { id: 2, name: "Madhabdi", zilla_id: 1 },
//   ...
// ]

Works identically with require(...):

const { getAllDivision } = require("@techvius/bd-geo-address");

A common use case is populating cascading dropdowns in an address form: fetch divisions, let the user pick one, call getZillaByDivisionId with its id, then getThanaByZillaId once a zilla is picked.

API reference

getAllDivision(): Division[]

Returns all 8 divisions of Bangladesh.

getZillaByDivisionId(divisionId: number): Zilla[]

Returns all zillas belonging to divisionId. Returns [] if divisionId doesn't match any division — it never throws.

| Parameter | Type | Description | | ------------ | -------- | ----------------------------------------------- | | divisionId | number | The id of a division from getAllDivision(). |

getThanaByZillaId(zillaId: number): Thana[]

Returns all thanas belonging to zillaId. Returns [] if zillaId doesn't match any zilla — it never throws.

| Parameter | Type | Description | | --------- | -------- | --------------------------------------------------- | | zillaId | number | The id of a zilla from getZillaByDivisionId(). |

Types

interface Division {
  id: number;
  name: string;
}

interface Zilla {
  id: number;
  name: string;
  division_id: number;
}

interface Thana {
  id: number;
  name: string;
  zilla_id: number;
}

Data

8 divisions, 64 zillas, 554 thanas. Sourced from Bangladesh's official administrative division list. IDs are stable integers assigned in a fixed order and won't change between versions of this package (adding new entries only appends new ids; it never renumbers existing ones).

Contributing

Contributions are welcome — bug fixes, data corrections, and small improvements in particular.

Setup

git clone https://github.com/moniruzzamanrony/bd-geo-address.git
cd bd-geo-address
npm install

Project layout

• data-source/data.xlsx — the source spreadsheet for the administrative hierarchy.
• scripts/build-data.ts — generates the files under src/data from data-source/data.xlsx. Run it with npm run build:data after editing the spreadsheet.
• src/ — package source (index.ts, types.ts, generated data/).
• test/ — Vitest test suite, including a data-integrity check that validates every zilla/thana references a valid parent id.

Workflow

1. Fork the repo and create a branch off main.
2. Make your change. If it touches the administrative data, edit data-source/data.xlsx and regenerate with npm run build:data rather than hand-editing files in src/data.
3. Run the checks locally before opening a PR:

   npm run lint   # tsc --noEmit
   npm test       # vitest run
   npm run build  # tsup

4. Open a pull request describing the change and, for data changes, the source you used to verify it.

Guidelines

• Keep the package's scope in mind — this repo intentionally does not include Bangla names, postal codes, union-level data, or geocoding.
• Existing ids are stable and must never be renumbered or reused; new entries are appended.
• No runtime dependencies — keep dependencies empty.

Reporting issues

Use GitHub Issues for bugs, incorrect data, or feature requests.

License

MIT © Moniruzzaman Rony