Introduction
The Nepal Administrative Divisions API provides programmatic access to comprehensive data about Nepal’s provinces, districts, and municipalities. This REST API is built with Flask-RESTX and returns all responses in JSON format.Base URL
All API requests are made to endpoints prefixed with/api:
Interactive Documentation
The API includes interactive Swagger documentation where you can explore and test all endpoints:Access the interactive Swagger API documentation at the
/docs endpoint on the live application for testing endpoints in your browser.Response Format
All API responses are returned in JSON format with appropriate HTTP status codes:200 OK- Successful request404 Not Found- Resource not found (e.g., invalid province or district)500 Internal Server Error- Server error
Available Endpoints
The API is organized into three main namespaces:Provinces
Access data for all 7 provinces of Nepal
Districts
Query districts by province ID or name
Municipalities
Retrieve municipalities by district or province
Provinces Endpoint
GET/api/provinces/
Returns a list of all provinces in Nepal with their details.
Response fields:
id(integer) - Province IDname(string) - Province namearea_sq_km(string) - Area in square kilometerswebsite(string) - Official province websiteheadquarter(string) - Province headquarter city
Districts Endpoint
GET/api/districts/
Returns districts based on optional query parameters.
Query parameters:
province_id(integer, optional) - Filter by province IDprovince_name(string, optional) - Filter by province name
id(integer) - District IDname(string) - District namearea_sq_km(string) - Area in square kilometerswebsite(string) - Official district websiteheadquarter(string) - District headquarter
- Without parameters: Returns all districts across all provinces
- With
province_idorprovince_name: Returns districts within that province
Municipalities Endpoint
GET/api/municipalities/
Returns municipalities based on optional query parameters.
Query parameters:
province_id(integer, optional) - Filter by province IDprovince_name(string, optional) - Filter by province namedistrict_id(integer, optional) - Filter by district IDdistrict_name(string, optional) - Filter by district name
id(integer) - Municipality IDcategory_id(integer) - Municipality category IDname(string) - Municipality namearea_sq_km(string) - Area in square kilometerswebsite(string) - Official municipality websitewards(array of integers) - List of ward numbers
- Without parameters: Returns all municipalities across Nepal
- With
province_idorprovince_nameonly: Returns all municipalities in that province - With province and district filters: Returns municipalities in that specific district
Example Requests
Data Source
The API loads data from a remote source specified in theNEPAL_ADMIN_DATA_URL environment variable. If the remote source is unavailable, it falls back to a local JSON file to ensure continuous availability.