Documentation
Complete guide for using the address-bd package in your projects.
Installation
Install the package using your preferred package manager:
bash
pnpm add address-bdQuick Start
Get started with the package in just a few lines of code:
typescript
import bdAddress from 'address-bd';
// Get all divisions
const divisions = await bdAddress.getAllDivisions();
console.log(divisions);
// [{ id: 1, name: 'Dhaka', bnName: 'ঢাকা', slug: 'dhaka', ... }]
// Search for locations
const results = await bdAddress.search('dhaka');
console.log(results);
// { divisions: [...], districts: [...], upazilas: [...] }
// Get full address hierarchy
const address = await bdAddress.getFullAddress(1);
console.log(address.formatEnglish()); // "Savar, Dhaka, Dhaka"
console.log(address.formatBengali()); // "সাভার, ঢাকা, ঢাকা"API Reference
Getting Locations
getAllDivisions()
Returns all 8 divisions of Bangladesh.
typescript
const divisions = await bdAddress.getAllDivisions();
// Returns: Promise<Division[]>getAllDistricts()
Returns all 64 districts of Bangladesh.
typescript
const districts = await bdAddress.getAllDistricts();
// Returns: Promise<District[]>getAllUpazilas()
Returns all 495 upazilas of Bangladesh.
typescript
const upazilas = await bdAddress.getAllUpazilas();
// Returns: Promise<Upazila[]>Search
search(query, options?)
Fuzzy search across all location types with customizable options.
typescript
const results = await bdAddress.search('dhaka');
// Returns: Promise<LocationSearchResult>
// With options
const results = await bdAddress.search('dhaka', {
includeEnglish: true,
includeBengali: true,
limit: 10,
threshold: 0.3,
types: ['division', 'district', 'upazila'],
});autocomplete(query, options?)
Prefix search for dropdown/typeahead functionality.
typescript
const suggestions = await bdAddress.autocomplete('dh');
// Returns: Promise<AutocompleteResult[]>Validation
isDistrictInDivision(districtId, divisionId)
Validates if a district belongs to a division.
typescript
const isValid = await bdAddress.isDistrictInDivision(1, 1);
// Returns: Promise<boolean>Formatting
formatAddress(address, options?)
Format addresses in multiple styles and languages.
typescript
const address = await bdAddress.getFullAddress(1);
// English format
bdAddress.formatAddressEnglish(address);
// Returns: "Savar, Dhaka, Dhaka"
// Bengali format
bdAddress.formatAddressBengali(address);
// Returns: "সাভার, ঢাকা, ঢাকা"
// Custom format
bdAddress.formatAddress(address, {
language: 'en',
separator: ' | ',
includeUpazila: true,
includeDistrict: true,
includeDivision: true,
});
// Returns: "Savar | Dhaka | Dhaka"Statistics
getStats()
Get overall statistics about the address data.
typescript
const stats = await bdAddress.getStats();
// Returns: Promise<LocationStats>
// {
// totalDivisions: 8,
// totalDistricts: 64,
// totalUpazilas: 495,
// divisionDistrictMap: { 1: 13, 2: 11, ... },
// districtUpazilaMap: { 1: 12, 2: 14, ... }
// }TypeScript Types
The package provides comprehensive TypeScript types for type safety:
typescript
import type {
Division,
District,
Upazila,
FullAddress,
LocationSearchResult,
SearchOptions,
FormatOptions,
LocationStats,
} from 'address-bd';
// Example: Type-safe function
async function processLocation(division: Division) {
console.log(`${division.name} (${division.bnName})`);
console.log(`Coordinates: ${division.coordinates?.latitude}, ${division.coordinates?.longitude}`);
}Examples
React Location Selector
Create a cascading dropdown for location selection:
typescript
import { useState, useEffect } from 'react';
import bdAddress from 'address-bd';
function LocationSelector() {
const [divisions, setDivisions] = useState([]);
const [districts, setDistricts] = useState([]);
const [upazilas, setUpazilas] = useState([]);
useEffect(() => {
bdAddress.getAllDivisions().then(setDivisions);
}, []);
const handleDivisionChange = async (divisionId: number) => {
const dists = await bdAddress.getDistrictsByDivision(divisionId);
setDistricts(dists);
setUpazilas([]);
};
const handleDistrictChange = async (districtId: number) => {
const upzs = await bdAddress.getUpazilasByDistrict(districtId);
setUpazilas(upzs);
};
return (
<div>
<select onChange={(e) => handleDivisionChange(Number(e.target.value))}>
<option value="">Select Division</option>
{divisions.map((d) => (
<option key={d.id} value={d.id}>{d.name}</option>
))}
</select>
{/* Similar for district and upazila */}
</div>
);
}