Simple, reliable, and up-to-date REST API for Kenyan administrative boundaries.

MtaaAPI provides developers with a stable and easy-to-use interface to access data on Kenya's 47 Counties, 290+ Constituencies, and their respective Wards. Stop scraping and start building.

---

Key Features

• Comprehensive Data: Access all 47 counties, constituencies, and wards with their official codes.
• RESTful Architecture: Clean, predictable, and resource-oriented URLs.
• Secure: API key authentication and rate limiting to prevent abuse.
• Interactive Documentation: Explore and test endpoints live with our auto-generated Swagger/OpenAPI documentation.
• Open Source: Built by the community, for the community. Contributions are welcome!

Live API & Documentation

The API is live and ready to use.

• Base URL: https://api.mtaa-bitrooted.com/api/v1/
• Interactive Docs: View the Swagger Documentation

Getting Started

1. Get an API Key: You will need to generate an API key from the admin panel to use the API.
2. Make a Request: Include your API key in the Authorization header.

Authorization: Api-Key <YOUR_API_KEY>

Example Endpoints (v1)

Method	Endpoint	Description
GET	/api/v1/counties/	List all counties
GET	/api/v1/counties/<id>/	County detail + constituencies
GET	/api/v1/constituencies/	List all constituencies
GET	/api/v1/wards/	List all wards

Example Usage

# Get all counties
curl -H "Authorization: Api-Key <YOUR_API_KEY>" https://api.mtaa-bitrooted.com/api/v1/counties/

# Get a specific county by its code (e.g., Mombasa)
curl -H "Authorization: Api-Key <YOUR_API_KEY>" https://api.mtaa-bitrooted.com/api/v1/counties/1/

# Get all constituencies
curl -H "Authorization: Api-Key <YOUR_API_KEY>" https://api.mtaa-bitrooted.com/api/v1/constituencies/

# Get a specific constituency by its code (e.g., Changamwe)
curl -H "Authorization: Api-Key <YOUR_API_KEY>" https://api.mtaa-bitrooted.com/api/v1/constituencies/001/

---

Local Development Setup

Want to run MtaaAPI on your own machine? Follow these steps.

Prerequisites

• Python 3.11+
• Django 4+
• Git
• A virtual environment tool (venv)

Installation

1. Clone the repository:

   git clone https://github.com/your-username/mtaaAPI.git
   cd mtaaAPI

2. Create and activate a virtual environment:

   uv venv venv
   source venv/bin/activate
   # On Windows: venv\Scripts\activate

3. Install dependencies:

   uv pip install -r requirements.txt
   

4. Run database migrations:

   python manage.py migrate

5. Create an admin superuser:

   python manage.py createsuperuser

6. Load the initial location data:

   python manage.py load_locations

7. Run the development server:

   python manage.py runserver

The API will now be available at http://127.0.0.1:9000.

---

How to Contribute

We welcome contributions of all kinds! Whether it's updating data, adding features, fixing bugs, or improving documentation, your help is appreciated.

Please read our CONTRIBUTING.md file for details on our code of conduct and the process for submitting pull requests.

The most immediate need is ensuring data accuracy. If you find an error in a county, constituency, or ward name/code, please raise an issue or submit a pull request to update the load_regions.py command.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.