Documentation & API Guide

Complete reference for installation, helper methods, GeoJSON boundaries, and contributing.

1. Getting Started

The bangladesh-geojson library is zero-dependency, works seamlessly in Node.js, Next.js, Vite, and React, and ships with complete TypeScript type definitions. The data lives inside the package — no internet needed once installed.

npm install bangladesh-geojson

2. Data Models (TypeScript Interfaces)

All records include both English and Bengali names along with geographic centers where applicable.

export interface Division {
  id: string;        // '1' - '8'
  name: string;      // 'Dhaka', 'Rangpur', etc.
  bn_name: string;   // 'ঢাকা', 'রংপুর', ইত্যাদি
  lat: string;       // Geographic latitude
  long: string;      // Geographic longitude
}

export interface District {
  id: string;        // '1' - '64'
  division_id: string;
  name: string;
  bn_name: string;
  lat: string;
  long: string;
}

export interface Upazila {
  id: string;        // '1' - '494'
  district_id: string;
  name: string;
  bn_name: string;
}

export interface Postcode {
  division_id: string;
  district_id: string;
  upazila: string;
  postOffice: string;
  postCode: string;  // e.g. '1212'
}

3. Core API Functions

Convenient helper methods exported by the root package.

getDivisions()→ Division[]

Returns all 8 administrative divisions of Bangladesh with IDs, bilingual names, and geographic centers.

import bd from 'bangladesh-geojson';
const divisions = bd.getDivisions();
console.log(divisions);
// [{ id: '1', name: 'Barishal', bn_name: 'বরিশাল', lat: '22.7010', long: '90.3535' }, ...]

getDivisionById(id)→ Division | undefined

Finds a specific division by its numeric string ID (1 through 8).

const dhaka = bd.getDivisionById('3');
console.log(dhaka.bn_name); // 'ঢাকা'

getDistricts()→ District[]

Returns all 64 districts mapped to division IDs with geographic coordinates.

const allDistricts = bd.getDistricts();

getDistrictsByDivision(divisionId)→ District[]

Returns all districts within a specified division ID.

// All districts in Rangpur Division (id: '7')
const rangpurDistricts = bd.getDistrictsByDivision('7');

getUpazilas()→ Upazila[]

Returns all 494+ upazilas across Bangladesh mapped to districts.

const allUpazilas = bd.getUpazilas();

getUpazilasByDistrict(districtId)→ Upazila[]

Returns all upazilas inside a target district ID.

// Upazilas in Bogura (districtId: '3')
const upazilas = bd.getUpazilasByDistrict('3');

getPostcodes()→ Postcode[]

Returns all 1,349+ post office entries with 4-digit post codes.

const postcodes = bd.getPostcodes();

getPostcodesByDistrict(districtId)→ Postcode[]

Returns all post offices and postal codes belonging to a specific district.

const dhakaPostcodes = bd.getPostcodesByDistrict('1');

search(query, limit?)→ SearchHit[]

Deep bilingual search across division names, district names, upazila names, and postcodes in English or বাংলা.

const matches = bd.search('Mirpur');
// or Bangla search:
const banglaMatches = bd.search('কুড়িগ্রাম');

getFullHierarchy()→ HierarchyDivision[]

Returns a nested tree where each division contains its districts, and each district contains its upazilas.

const tree = bd.getFullHierarchy();
// tree[0].districts[0].upazilas

4. Direct Subpath Imports

Each dataset has its own subpath export, so your bundler (Webpack / Turbopack / Vite) only bundles what you import:

import divisions from 'bangladesh-geojson/divisions';
import districts from 'bangladesh-geojson/districts';
import upazilas  from 'bangladesh-geojson/upazilas';
import postcodes from 'bangladesh-geojson/postcodes';

import boundary  from 'bangladesh-geojson/boundary'; // Upazila polygons (~3.5 MB)
import bazars    from 'bangladesh-geojson/bazars';   // ~3,500 marketplaces
import routes    from 'bangladesh-geojson/routes';   // Major highways
import dhaka     from 'bangladesh-geojson/dhaka-city';

5. React Address Cascading Example

Here is a drop-in pattern to implement a Division → District → Upazila cascade dropdown in React or Next.js:

import { useState } from 'react';
import bd from 'bangladesh-geojson';

export default function ShippingAddressSelector() {
  const [divisionId, setDivisionId] = useState('');
  const [districtId, setDistrictId] = useState('');
  const [upazilaId, setUpazilaId] = useState('');

  const divisions = bd.getDivisions();
  const districts = divisionId ? bd.getDistrictsByDivision(divisionId) : [];
  const upazilas = districtId ? bd.getUpazilasByDistrict(districtId) : [];

  return (
    <div className="grid grid-cols-3 gap-3">
      {/* 1. Division */}
      <select value={divisionId} onChange={(e) => {
        setDivisionId(e.target.value);
        setDistrictId('');
        setUpazilaId('');
      }}>
        <option value="">Select Division</option>
        {divisions.map((d) => (
          <option key={d.id} value={d.id}>{d.name} ({d.bn_name})</option>
        ))}
      </select>

      {/* 2. District */}
      <select value={districtId} onChange={(e) => {
        setDistrictId(e.target.value);
        setUpazilaId('');
      }} disabled={!divisionId}>
        <option value="">Select District</option>
        {districts.map((d) => (
          <option key={d.id} value={d.id}>{d.name} ({d.bn_name})</option>
        ))}
      </select>

      {/* 3. Upazila */}
      <select value={upazilaId} onChange={(e) => setUpazilaId(e.target.value)} disabled={!districtId}>
        <option value="">Select Upazila</option>
        {upazilas.map((u) => (
          <option key={u.id} value={u.id}>{u.name} ({u.bn_name})</option>
        ))}
      </select>
    </div>
  );
}

6. Licenses & Attribution

• Code & Library: MIT License. Free for commercial and personal apps.

• Boundary Data: CC BY 4.0, sourced from geoBoundaries (gbOpen, ADM3). Underlying source: Bangladesh Bureau of Statistics (BBS).

• OSM-derived layers (Bazars & Routes): Open Database License (ODbL 1.0). Attribution: © OpenStreetMap contributors — odbl-1.0.