@bangladeshi/bangladesh-address/README.md

A simple npm package for Bangladesh's administrative divisions, districts, upazilas, and metropolitan thanas.

# Bangladesh Address (division, district, upazila, thana)

A simple npm package that exports methods representing divisions, districts, upazilas and thanas (metropolitan police stations) of Bangladesh.

## Data Coverage

- **8 Divisions** - All administrative divisions
- **64 Districts** - All districts
- **495 Upazilas** - All upazilas (updated July 2021 with Eidgaon, Dasar, Madhyanagar)
- **26 Metropolitan Thanas** - Police stations in Dhaka, Chattogram, Rajshahi, Khulna

## Installation

```bash
npm i @bangladeshi/bangladesh-address
```

## Usage

### CommonJS
```javascript
const address = require('@bangladeshi/bangladesh-address')
```

### ES Modules / TypeScript
```typescript
import { allDivision, districtsOf, upazilasOf, DivisionName } from '@bangladeshi/bangladesh-address'
```

## API Reference

### Division

```javascript
allDivision()
// Returns: ['Dhaka', 'Chattogram', 'Mymensingh', ...]

divisionalDataOf(DivisionName.Dhaka)
// Returns: All districts and upazilas of Dhaka division
```

### Districts

```javascript
districtsOf(DivisionName.Dhaka)
// Returns: Districts of Dhaka division

allDistricts()
// Returns: Array of all 64 district names
```

### Upazilas

```javascript
upazilasOf("Tangail")
// Returns: Array of upazila objects for Tangail district

upazilaNamesOf("Tangail")
// Returns: Array of upazila names (strings) for Tangail district

allUpazila()
// Returns: Array of all 495 upazila names

isUpazila("Savar")
// Returns: true (Savar is an upazila)

getUpazila("Savar")
// Returns: { upazila: "Savar", district: "Dhaka", division: "Dhaka" }
```

### Thanas (Metropolitan Police Stations)

```javascript
allThana()
// Returns: Array of all 26 thana objects

allThanaNames()
// Returns: Array of all 26 thana names (strings)

thanasOf("Dhaka")
// Returns: Array of thana objects for Dhaka (15 thanas)

thanaNamesOf("Dhaka")
// Returns: Array of thana names (strings) for Dhaka

isThana("Gulshan")
// Returns: true (Gulshan is a metropolitan thana)

isThana("Savar")
// Returns: false (Savar is an upazila, not a thana)

isThana("Kotwali", "Dhaka")
// Returns: true (disambiguate with district context)

getThana("Gulshan")
// Returns: { thana: "Gulshan", district: "Dhaka", division: "Dhaka" }

getThana("Kotwali", "Chattogram")
// Returns: { thana: "Kotwali", district: "Chattogram", division: "Chattogram" }
```

### Validation Functions

```javascript
isValidDivision("Dhaka")
// Returns: true

isValidDivision("InvalidName")
// Returns: false

isValidDistrict("Tangail")
// Returns: true

isValidDistrict("Savar")
// Returns: false (Savar is an upazila, not a district)
```

### Reverse Lookups

```javascript
getDivisionOfDistrict("Tangail")
// Returns: "Dhaka"

getDivisionOfDistrict("Cox's Bazar")
// Returns: "Chattogram"

getDistrictOfUpazila("Savar")
// Returns: "Dhaka"

getDistrictOfUpazila("Mohammadpur", "Khulna")
// Returns: "Magura" (disambiguate with division context)
```

### Get Upazilas by Division

```javascript
upazilasOfDivision("Sylhet")
// Returns: Array of all upazila objects in Sylhet division

upazilaNamesOfDivision("Sylhet")
// Returns: Array of all upazila names (strings) in Sylhet division
```

### Search Locations

```javascript
searchLocations("pur")
// Returns: Array of matching locations across divisions, districts, upazilas, and thanas
// [
//   { name: "Rangpur", type: "division" },
//   { name: "Rangpur", type: "district", division: "Rangpur" },
//   { name: "Mirpur", type: "thana", district: "Dhaka", division: "Dhaka" },
//   ... more matches
// ]
```

### Raw Data Access

```javascript
import { upazilaData, thanaData } from '@bangladeshi/bangladesh-address'

// upazilaData: Array of all 495 upazila objects
// thanaData: Array of all 26 thana objects
```

### Types

```typescript
import { DivisionName, DistrictName, Upazila, Thana, SearchResult } from '@bangladeshi/bangladesh-address'

// Division enum
DivisionName.Dhaka
DivisionName.Chattogram
DivisionName.Mymensingh
DivisionName.Khulna
DivisionName.Rajshahi
DivisionName.Rangpur
DivisionName.Sylhet
DivisionName.Barisal

// DistrictName type (all 64 districts)
type DistrictName = "Dhaka" | "Chattogram" | "Khulna" | ... // 64 districts

// Upazila interface
interface Upazila {
  upazila: string;
  district: string;
  division: string;
}

// Thana interface
interface Thana {
  thana: string;
  district: string;
  division: string;
  type: "thana";
}
```

## Metropolitan Thana Distribution

| City | Thana Count |
|------|-------------|
| Dhaka | 15 |
| Chattogram | 6 |
| Khulna | 3 |
| Rajshahi | 2 |

## Database Dumps (For Non-JavaScript Projects)

If you're using PHP, Python, Java, Go, Ruby, or any other language, you can use our pre-built database dumps instead of the npm package.

### Available Formats

| Database | File |
|----------|------|
| MySQL | [`db/mysql/bangladesh-address.sql`](db/mysql/bangladesh-address.sql) |
| PostgreSQL | [`db/postgresql/bangladesh-address.sql`](db/postgresql/bangladesh-address.sql) |
| SQLite | [`db/sqlite/bangladesh-address.sql`](db/sqlite/bangladesh-address.sql) |
| MongoDB | [`db/mongodb/`](db/mongodb/) |

### Quick Import

```bash
# MySQL
mysql -u username -p database_name < db/mysql/bangladesh-address.sql

# PostgreSQL
psql -U username -d database_name -f db/postgresql/bangladesh-address.sql

# SQLite
sqlite3 bangladesh.db < db/sqlite/bangladesh-address.sql

# MongoDB
mongoimport --db bangladesh --collection divisions --file db/mongodb/divisions.json --jsonArray
```

See [db/README.md](db/README.md) for full documentation, schema details, and example queries.

## Contribution

If you want to contribute please follow the guideline. [Contribution](https://github.com/rajuAhmed1705/bangladesh-address/blob/master/CONTRIBUTING.md)