souravio

A lightweight, zero-dependency npm package providing comprehensive administrative data about Bangladesh — including all 8 divisions, 64 districts, and 495 upazilas with both English and Bengali (বাংলা) names.

Features

• All 8 divisions, 64 districts, and 495 upazilas of Bangladesh
• English and Bengali (বাংলা) name support
• Case-insensitive search by English or Bengali name
• Lookup by ID or hierarchical relationships (division → districts → upazilas)
• Full TypeScript type definitions included
• Zero runtime dependencies
• Supports both CommonJS and ESM

Installation

npm install souravio

Usage

CommonJS

const {
  getAllDivisions,
  getDistrictsByDivisionId,
  getUpazilasByDistrictId,
  searchDistrict,
  searchDivision,
} = require("souravio");

// Get all 8 divisions
const divisions = getAllDivisions();

// Get districts in a specific division (e.g., Dhaka - ID 3)
const districts = getDistrictsByDivisionId(3);

// Get upazilas in a specific district (e.g., Barguna - ID 34)
const upazilas = getUpazilasByDistrictId(34);

// Search for a district by name (case-insensitive)
const feni = searchDistrict("Feni");
console.log(feni.bn_name); // 'ফেনী'

// Search using Bengali name
const dhaka = searchDivision("ঢাকা");
console.log(dhaka.name); // 'Dhaka'

ESM / TypeScript

import {
  getAllDivisions,
  getDistrictsByDivisionId,
  searchDistrict,
  type Division,
  type District,
  type Upazila,
} from "souravio";

const divisions: Division[] = getAllDivisions();
const dhakaDistricts: District[] = getDistrictsByDivisionId(3);
const gazipur: District | null = searchDistrict("Gazipur");

Browser / Web View

import {
  getWebData,
  findBestMatch,
  buildRedirectUrl,
  redirectToLocation,
} from "souravio/browser";

const data = getWebData();
const summary = findBestMatch("Dhaka");
const redirectUrl = buildRedirectUrl("Gazipur", "/web/index.html");

Open the package demo at web/index.html after building to explore divisions, districts, upazilas, and redirect search from the browser.

API Reference

Divisions

| Function | Signature | Description | | ----------------- | -------------------------------------------- | -------------------------------------------------- | | getAllDivisions | () => Division[] | Returns all 8 divisions | | getDivisionById | (id: string \| number) => Division \| null | Returns a division by its ID | | searchDivision | (name: string) => Division \| null | Case-insensitive search by English or Bengali name |

Districts

| Function | Signature | Description | | -------------------------- | ---------------------------------------------- | -------------------------------------------------- | | getAllDistricts | () => District[] | Returns all 64 districts | | getDistrictById | (id: string \| number) => District \| null | Returns a district by its ID | | getDistrictsByDivisionId | (divisionId: string \| number) => District[] | Returns districts under a division | | searchDistrict | (name: string) => District \| null | Case-insensitive search by English or Bengali name |

Upazilas

| Function | Signature | Description | | ------------------------- | --------------------------------------------- | -------------------------------------------------- | | getAllUpazilas | () => Upazila[] | Returns all 495 upazilas | | getUpazilaById | (id: string \| number) => Upazila \| null | Returns an upazila by its ID | | getUpazilasByDistrictId | (districtId: string \| number) => Upazila[] | Returns upazilas under a district | | searchUpazila | (name: string) => Upazila \| null | Case-insensitive search by English or Bengali name |

Types

interface Division {
  id: string;
  name: string;
  bn_name: string;
  url: string;
}

interface District {
  id: string;
  division_id: string;
  name: string;
  bn_name: string;
  lat: string;
  lon: string;
  url: string;
}

interface Upazila {
  id: string;
  district_id: string;
  name: string;
  bn_name: string;
  url: string;
}

Data

The package includes static JSON data for all administrative regions of Bangladesh:

| Level | Count | Fields | | --------- | ----- | --------------------------------------------- | | Divisions | 8 | id, name, bn_name, url | | Districts | 64 | id, division_id, name, bn_name, lat, lon, url | | Upazilas | 495 | id, district_id, name, bn_name, url |

Data is sourced from reliable open-source repositories mapping Bangladesh administrative boundaries.

Development

# Install dependencies
npm install

# Build (CJS + ESM + type declarations)
npm run build

# Watch mode
npm run dev

# Type check
npm run lint

# Run tests
npm test

Project Structure

├── src/
│   ├── index.ts          # All exported functions
│   ├── browser.ts        # Browser/web helper exports
│   ├── types.ts          # TypeScript interfaces
 │   └── data/
 │       ├── divisions.json
 │       ├── districts.json
 │       └── upazilas.json
 ├── dist/                  # Built output (CJS, ESM, .d.ts)
 ├── web/                   # Browser demo and modern web view files
 │   ├── index.html
 │   └── style.css

License

GPL-3.0