Power Distributors of Bangladesh API

A production-grade, high-performance RESTful JSON API providing normalized, structured, and hierarchical access to all electric power distribution companies across Bangladesh.

---

🚀 Features

• Standardized Response Format: Predictable success and error JSON envelopes for smooth client integration.
• Hierarchical & Relational Data: Structured access across 6 major power distributors, 12 zones, 34 operation circles, and 308 sales & distribution divisions / PBS offices.
• Sequential Tree Views: Dedicated full hierarchy tree endpoints per distributor (/api/v1/distributors/{code}/tree).
• Global Search: Query across all entities by keyword (/api/v1/search?q={query}).
• Pagination & Filtering: Built-in limit/page pagination and relational filtering.
• Zero Overhead: In-memory indexed data model for ultra-fast response times.
• Vercel & WSGI Ready: Native support for local development, WSGI servers, and serverless platforms like Vercel.

---

📊 Data Collection & Sources

Power Distributor	Source Link
BPDB - Bangladesh Power Development Board	bpdb.portal.gov.bd
DESCO - Dhaka Electric Supply Company Limited	desco.gov.bd
DPDC - Dhaka Power Distribution Company Limited	dpdc.org.bd
NESCO - Northern Electricity Supply Company PLC	customer.nesco.gov.bd
WZPDCL - West Zone Power Distribution Company Limited	wzpdcl.org.bd
BREB - Bangladesh Rural Electrification Board	reb.portal.gov.bd
Ministry Grievance Submission Portal	202.51.182.190:5412/ticket

---

📌 API Endpoints Reference

Base URL: /api/v1

1. General & System Endpoints

Method	Endpoint	Description
GET	/	Root directory and API metadata
GET	/api/v1/health	Service health status and API version
GET	/api/v1/summary	Aggregated network count (distributors, zones, circles, divisions)

2. Distributor Endpoints

Method	Endpoint	Description
GET	/api/v1/distributors	List all 6 power distribution companies
GET	/api/v1/distributors/{code}	Get details for a specific distributor (e.g., bpdb, desco)
GET	/api/v1/distributors/{code}/tree	Full sequential hierarchy tree for a distributor
GET	/api/v1/distributors/{code}/zones	List all zones under a distributor
GET	/api/v1/distributors/{code}/circles	List circles under a distributor (optional zone_id filter)
GET	/api/v1/distributors/{code}/divisions	List divisions/offices under a distributor

3. Global Entities & Search Endpoints

Method	Endpoint	Query Parameters	Description
GET	/api/v1/zones	None	List all zones across all distributors
GET	/api/v1/circles	zone_id	List circles (filterable by zone ID)
GET	/api/v1/divisions	distributor, zone_id, circle_id, q, page, limit	Paginated & filtered list of sales & distribution divisions / offices
GET	/api/v1/search	q (required)	Global keyword search across distributors, zones, circles, and divisions

---

🛠️ Standard Response & Error Envelopes

Success Envelope

{
  "success": true,
  "status_code": 200,
  "message": "Distributors list retrieved successfully",
  "data": [
    {
      "id": "bpdb",
      "code": "BPDB",
      "name": "Bangladesh Power Development Board",
      "full_name": "BPDB - Bangladesh Power Development Board",
      "zone_count": 4,
      "circle_count": 13,
      "division_count": 64
    }
  ]
}

Paginated Envelope

{
  "success": true,
  "status_code": 200,
  "message": "Distributor divisions retrieved successfully",
  "data": [ ... ],
  "meta": {
    "total": 80,
    "page": 1,
    "limit": 20,
    "total_pages": 4,
    "has_next": true,
    "has_prev": false
  }
}

Error Envelope

{
  "success": false,
  "status_code": 404,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Distributor with identifier 'invalid_code' was not found",
    "details": null
  }
}

---

💡 Example Requests & Responses

1. Network Summary (GET /api/v1/summary)

{
  "success": true,
  "status_code": 200,
  "message": "Power distribution network summary retrieved successfully",
  "data": {
    "total_distributors": 6,
    "total_zones": 12,
    "total_circles": 34,
    "total_divisions": 308
  }
}

2. Global Search (GET /api/v1/search?q=Agrabad)

{
  "success": true,
  "status_code": 200,
  "message": "Search results retrieved successfully",
  "data": {
    "distributors": [],
    "zones": [],
    "circles": [],
    "divisions": [
      {
        "id": "bpdb-z-chattogram-south-zone-c-conservation-and-management-circle-chatto-metro-west-d-agrabad",
        "distributor_id": "bpdb",
        "distributor_code": "BPDB",
        "zone_id": "bpdb-z-chattogram-south-zone",
        "zone_name": "Chattogram (South Zone)",
        "circle_id": "bpdb-z-chattogram-south-zone-c-conservation-and-management-circle-chatto-metro-west",
        "circle_name": "Conservation and Management Circle, Chatto Metro (West)",
        "name": "Agrabad",
        "type": "Sales & Distribution Division"
      }
    ]
  }
}

---

💻 Local Development

Setup & Run

1. Install dependencies:

   pip install -r requirements.txt

2. Start the local API server:

   python run.py

   Server will run on http://127.0.0.1:5000.

---

☁️ Deployment

Deploy seamlessly to Vercel:

vercel --prod

---

🤝 Contributions

Contributions are welcome:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes
4. Open a Pull Request

---

⚠️ Disclaimer

Data provided in this repository was gathered from official public utility websites. Please verify information before using it for critical applications.
Data updated as of May 7, 2024.