npm version downloads TypeScript MIT Zero deps GitHub Stars

Bangladesh Geo Data
for Every JS/TS Framework

Divisions · Districts · Upazilas · Unions · Postcodes Bilingual (EN / বাংলা) · Zero required dependencies · Full TypeScript

npm install bd-geo-info
—
Version
—
Monthly DLs
—
Total DLs
—
GitHub Stars
—
Forks
—
Open Issues
Why bd-geo-info

Everything you need, nothing you don't

Built to work anywhere JavaScript runs — frontend, backend, serverless, or edge.

🔌

Framework Agnostic

Core utilities have zero runtime dependencies. Works with React, Vue, Angular, Svelte, NestJS, Express, or plain Node.js.

⚡

O(1) Lookups

Datasets indexed by parent ID — no linear scans across thousands of records. Instant results at any depth.

📦

Code Split

Large JSON datasets use dynamic import() and load on demand — never bloat your initial bundle.

🌐

Bilingual

Every entry has both English and বাংলা names. Switch output language with a single parameter.

🔷

Full TypeScript

Strict types for all data shapes and utilities. Separate types for core and React so non-React projects stay clean.

⚛️

Optional React UI

Pre-built cascading selects via bd-geo-info/react. Non-React users pay zero cost.

🗜️

Minified Data

All JSON assets minified at build time — ~300 KB saved vs raw source on every install.

🌲

Tree Shakeable

Declares "sideEffects": false. Bundlers drop every export you don't use.

Installation

Get started in seconds

npm
npm install bd-geo-info
yarn
yarn add bd-geo-info
pnpm
pnpm add bd-geo-info
bun
bun add bd-geo-info
Using React components? Also install React: npm install bd-geo-info react react-dom

Quick Start

index.ts
import { getDivisions, getDistricts, getUpazilas, getUnions } from 'bd-geo-info';

// All divisions (8 divisions of Bangladesh)
const divisions = await getDivisions('en');
// [{ value: '1', label: 'Barisal' }, { value: '2', label: 'Chattagram' }, ...]

// Districts for a division
const districts = await getDistricts('3', 'en');

// Upazilas for a district
const upazilas = await getUpazilas('47', 'en');

// Unions for an upazila
const unions = await getUnions('365', 'en');

// বাংলা output — just change the language param
const divisionsBn = await getDivisions('bn');
// [{ value: '1', label: 'বরিশাল' }, ...]
API Reference

All utility functions

Import from bd-geo-info — no framework required.

getDivisions async
getDivisions(language?: 'en' | 'bn'): Promise<{ value: string; label: string }[]>

Returns all 8 divisions of Bangladesh. Defaults to English.

const divisions = await getDivisions('en');
// [{ value: '1', label: 'Barisal' }, { value: '2', label: 'Chattagram' }, ...]
const divisionsBn = await getDivisions('bn');
// [{ value: '1', label: 'বরিশাল' }, ...]
getDistricts async
getDistricts(divisionId: string, language?: 'en' | 'bn'): Promise<{ value: string; label: string }[]>

Returns all districts belonging to a division.

const districts = await getDistricts('3', 'en');
// [{ value: '47', label: 'Dhaka' }, { value: '41', label: 'Gazipur' }, ...]
getUpazilas async
getUpazilas(districtId: string, language?: 'en' | 'bn'): Promise<(Upazila & { value: string; label: string })[]>

Returns all upazilas for a district. Includes full data fields alongside value / label.

const upazilas = await getUpazilas('47', 'en');
// [{ id: '530', district_id: '47', name: 'Mirpur', value: '530', label: 'Mirpur' }, ...]
getUnions async
getUnions(upazilaId: string, language?: 'en' | 'bn'): Promise<{ value: string; label: string; url?: string }[]>

Returns all unions for an upazila.

const unions = await getUnions('365', 'en');
// [{ value: '3272', label: 'Birulia', url: 'birulia.dhaka.gov.bd' }, ...]
getPostCode sync
getPostCode(params: { division?: string; district?: string; upazila?: string } | null): PostCode[]

Synchronous postcode lookup. Useful inline without await.

const codes = getPostCode({ district: '47', upazila: 'Mirpur' });
// [{ postCode: '1216', postOffice: 'Mirpur TSO', upazila: 'Mirpur', ... }]
formatAddress async
formatAddress(division, district, upazila, union, postCode, street, language?): Promise<string>

Resolves IDs to names and returns a human-readable formatted address string.

const addr = await formatAddress('3', '47', '365', '3272', '1340', 'House 5', 'en');
// "House 5, Birulia, Savar, Dhaka-1340, Dhaka"
validatePostCode sync
validatePostCode(postCode: string): boolean

Returns true for a valid 4-digit Bangladesh postcode.

validatePostCode('1216'); // true
validatePostCode('12');   // false
validatePostCode('abcd'); // false
Framework Guides

Works everywhere

The same three imports, any stack.

import { getDivisions, getDistricts, getUpazilas, getUnions, getPostCode } from 'bd-geo-info';

const divisions = await getDivisions('en');
const districts = await getDistricts('3', 'en');
const upazilas  = await getUpazilas('47', 'en');
const unions    = await getUnions('365', 'en');
const codes     = getPostCode({ district: '47', upazila: 'Mirpur' });
React Components

Pre-built UI for React

Import from bd-geo-info/react. Non-React projects are completely unaffected.

Available Components

AddressForm Full cascading form with validation, theming, bilingual support
DivisionSelect Standalone division dropdown
DistrictSelect Districts filtered by selected division
UpazilaSelect Upazilas filtered by selected district
UnionSelect Unions filtered by selected upazila

AddressForm Props

Prop Type Default
language 'en' | 'bn' 'en'
onChange (data) => void —
showPostCode boolean true
showUnion boolean true
validation AddressFormValidation —
customLabels AddressFormLabels —
theme Theme —
disabled boolean false
AddressPage.tsx
// Full address form
import { AddressForm } from 'bd-geo-info/react';
import type { AddressFormData } from 'bd-geo-info/react';

export default function Page() {
  return (
    <AddressForm
      language="en"
      onChange={(data: AddressFormData) => console.log(data)}
      showPostCode showUnion
      validation={{
        division: { required: true },
        district: { required: true },
      }}
      theme={{
        colors: { primary: '#2563eb' },
        borderRadius: '0.5rem',
      }}
    />
  );
}

// Individual composable selects
import {
  DivisionSelect, DistrictSelect,
  UpazilaSelect, UnionSelect
} from 'bd-geo-info/react';
import type { Division, District, Upazila } from 'bd-geo-info/react';

const [division, setDivision] = useState<Division>();
const [district, setDistrict] = useState<District>();

<DivisionSelect
  language="en"
  value={division}
  onChange={setDivision}
  customLabel="Division"
/>
<DistrictSelect
  division={division}
  onChange={setDistrict}
  customLabel="District"
/>
TypeScript Types

Full type coverage

Core types have no React dependency. React types live in a separate import path.

Core — bd-geo-info

import type {
  Division,       // id, name, bn_name, lat, long
  District,       // id, division_id, name, bn_name
  Upazila,        // id, district_id, name, bn_name
  UnionData,      // id, upazilla_id, name, bn_name
  PostCode,       // division_id, upazila, postCode
  AddressFormData,
  AddressFormValidation,
  ValidationRules,
  Theme,
} from 'bd-geo-info';

React — bd-geo-info/react

import type {
  AddressFormProps,
  AddressFormErrors,
  AddressFormLabels,
  SelectProps,
  PostOfficeSelectProps,
  // + all core types re-exported
} from 'bd-geo-info/react';
Overview • API Documentation • Live Playground • Sitemap • Robots.txt • GitHub (Open Source)
✓ Copied!