BD APIs – Bangladesh Geo Location API

Project Overview

BD APIs is a lightweight, blazing-fast, and completely free RESTful API that provides structured access to Bangladesh's complete administrative geography: 8 Divisions, 64 Districts, 495 Upazilas, and 4550+ Unions. All entities include names in both English and Bengali, making it ideal for bilingual applications.

The project includes an interactive API Explorer UI hosted at https://bdapis.vercel.app, allowing developers to test endpoints instantly without any authentication or API keys.

Built as an open-source project (GitHub: SudipMHX/bd-apis), it serves developers building location-based services, e-commerce delivery systems, government portals, form address pickers, demographic tools, and more.

Core Problem & Solution

Problem
Many existing Bangladesh location APIs were either paid, outdated, incomplete (missing unions or bilingual names), slow, or required complex authentication. Developers in Bangladesh often struggled to find a reliable, free, and maintained source for hierarchical geo-data.

Solution
BD APIs delivers:

• Always-free access with no API key
• Up-to-date data (reflecting 2025 administrative structure)
• Hierarchical filtering (division → district → upazila → union)
• Bilingual support
• Fast responses through caching and optimized data serving
• Clean, predictable JSON structure
• Interactive explorer for quick testing

Key Features

• Complete Bangladesh Geo Hierarchy — Divisions, Districts, Upazilas, Unions
• Bilingual Names — English + বাংলা for every entity
• Smart Filtering — Get districts of a division, upazilas of a district, unions of an upazila
• Global Search — /search/{query} endpoint with optional type filter
• No Authentication — Publicly accessible
• CORS Enabled — Ready for frontend usage
• Caching & Rate Limiting — Built-in performance & abuse protection
• Interactive API Explorer — Test all endpoints directly in browser
• Open Source — MIT licensed, community contributions welcome

Technical Architecture & Deep Dive

The API follows a simple yet performant architecture:

• Data Layer — Static JSON/JS files in src/database/ (fastest for read-heavy workload) + optional MongoDB for future scalability & indexing
• API Layer — Express.js routes under /geo/v2.0
• Performance Layer — node-cache for in-memory caching of frequent queries
• Hosting — Vercel serverless functions (automatic scaling, zero maintenance)
• Frontend — Simple HTML + CSS + vanilla JS explorer UI in /public

Frontend Architecture

The API Explorer is intentionally lightweight:

• Single-page layout with endpoint cards
• Real-time fetch using fetch() API
• Syntax-highlighted JSON responses
• Copy-to-clipboard functionality
• Responsive design for mobile developers

No heavy frameworks → keeps the landing page load time under 1 second.

In-App Preview

The live site offers a clean, modern interface showing key stats:

• 8 Divisions
• 64 Districts
• 495 Upazilas
• 4550+ Unions

Users can directly click endpoints like /geo/v2.0/divisions or try filtered routes like /geo/v2.0/districts/3 (Dhaka division districts).

Development Process & Challenges

Development Journey

1. Collected & cleaned geo-data from reliable sources + government publications
2. Structured hierarchical data in JSON format with bilingual fields
3. Built Express routes with proper parameter validation
4. Added caching layer to handle large union lists efficiently
5. Created beautiful API Explorer UI
6. Deployed to Vercel with custom domain
7. Wrote optimization guide (OPTIMIZATION.md) & maintained documentation

Major Challenges & Solutions

• Large union dataset → Solved with caching + selective population
• Serverless cold starts → Mitigated via Vercel edge caching + warm-up patterns
• Data freshness → Plan to add admin dashboard in future for easy updates
• Abuse prevention → Implemented lightweight rate limiting

The project is actively maintained and welcomes contributions for new features like coordinates, postcodes, or autocomplete search.