Skip to main content
This guide walks you through setting up the Nepal Administrative Divisions application on your local machine for development purposes.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.9 or higher
  • pip (Python package installer)
  • Git

​
Installation Steps

1

Clone the Repository

Clone the project repository from GitHub:
git clone https://github.com/sajan69/nepal-administrative-divisions.git
cd nepal-administrative-divisions
2

Create Virtual Environment

Create and activate a Python virtual environment:
python -m venv env
source env/bin/activate
3

Install Dependencies

Install all required Python packages from requirements.txt:
pip install -r requirements.txt
The following packages will be installed:
Flask==2.2.5
flask-restx==1.1.0
python-decouple==3.8
requests==2.32.3
Jinja2==3.1.2
# ... and other dependencies
4

Configure Environment Variables

Set up the required environment variable for the data source URL. See the Environment Variables page for detailed configuration.Create a .env file in the project root:
NEPAL_ADMIN_DATA_URL=https://your-data-source-url.com/nepal_data.json
The application fetches administrative division data from the URL specified in NEPAL_ADMIN_DATA_URL. If the URL is unavailable, it will fall back to the local data/updated_nepal_data.json file.
5

Run the Application

Start the Flask development server:
python app.py
You should see output similar to:
Fetching data from: https://your-data-source-url.com/nepal_data.json
Status Code: 200
 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://127.0.0.1:5000
6

Access the Application

Open your web browser and navigate to:
  • Web Interface: http://localhost:5000
  • API Documentation: http://localhost:5000/docs
The web interface provides:
  • Browse provinces, districts, and municipalities
  • Search functionality for administrative divisions
  • Interactive data visualization

​
Development Features

When running in debug mode (default for local development), the application includes:
  • Auto-reload: The server automatically restarts when you modify code files
  • Debug mode: Detailed error messages and stack traces
  • Swagger UI: Interactive API documentation at /docs

​
API Endpoints

Once running, you can test the following API endpoints: 
# Get all provinces
GET http://localhost:5000/api/provinces/

# Get districts in a specific province
GET http://localhost:5000/api/districts/?province_id=3
GET http://localhost:5000/api/districts/?province_name=Bagmati

# Get municipalities in a specific district
GET http://localhost:5000/api/municipalities/?province_id=3&district_id=27
GET http://localhost:5000/api/municipalities/?province_name=Bagmati&district_name=Kathmandu

​
Troubleshooting

If you encounter a “NEPAL_ADMIN_DATA_URL not found” error, ensure you’ve created the .env file with the correct environment variable.

​
Common Issues

Port already in use: If port 5000 is already in use, modify app.py to use a different port: 
if __name__ == '__main__':
    app.run(debug=True, port=5001)
Module not found errors: Ensure your virtual environment is activated and all dependencies are installed: 
source env/bin/activate  # or env\Scripts\activate on Windows
pip install -r requirements.txt

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us