🇹🇿 Tanzania Pincode Lookup API

🟩 This project is 100% complete 🎉

████████████████████████████████████████ 100%

A lightweight FastAPI service for looking up Tanzanian regions, cities, and districts from a 6-digit pincode.

The API is designed for applications such as e-commerce checkout forms, where a customer enters a pincode and the corresponding location information can be automatically populated.

✨ Features

• 🔎 Look up a location using a 6-digit pincode
• 📦 Perform bulk pincode lookups
• 🇹🇿 Tanzania-focused location data
• ✅ Automatic pincode validation using Pydantic
• ⚡ Fast API powered by FastAPI
• 🛡️ Custom error handling for invalid and unknown pincodes
• 📚 Interactive API documentation through FastAPI
• 🧩 Easy to integrate with checkout and address forms

🛠️ Tech Stack

• Python
• FastAPI
• Pydantic
• Uvicorn

📁 Project Structure

🇹🇿 EMTAA — Tanzania Pincode Lookup API
│
├── 📁 Scripts/
│   └── ⚙️ Supporting / utility scripts
│
├── 📄 main.py
│   └── 🚀 FastAPI application entry point
│       ├── API routes
│       ├── Pincode lookup
│       ├── Bulk lookup
│       └── Request / response handling
│
├── 📄 models.py
│   └── 🧩 Pydantic data models
│       ├── Request schemas
│       ├── Response schemas
│       └── Data validation
│
├── 📄 data.py
│   └── 🇹🇿 Tanzania pincode/location dataset
│       ├── Regions
│       ├── Cities
│       └── Districts
│
├── 📄 exceptions.py
│   └── ⚠️ Custom API exceptions
│       ├── Invalid pincode
│       ├── Pincode not found
│       └── Validation errors
│
├── 📄 requirements.txt
│   └── 📦 Python dependencies
│       ├── FastAPI
│       ├── Pydantic
│       └── Uvicorn
│
├── 📄 README.md
│   └── 📚 Project documentation
│       ├── Features
│       ├── Installation
│       ├── API usage
│       └── Examples
│
├── 📄 .gitignore
│   └── 🚫 Ignored files / directories
│
└── 📄 pyvenv.cfg
    └── 🐍 Python virtual-environment configuration


                ┌─────────────────────────┐
                │       Client / App       │
                │  E-commerce / Checkout   │
                └────────────┬────────────┘
                             │
                             │ 6-digit Pincode
                             ▼
                ┌─────────────────────────┐
                │        main.py           │
                │     FastAPI API Layer    │
                └────────────┬────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
       ┌────────────┐ ┌────────────┐ ┌──────────────┐
       │  models.py │ │  data.py   │ │ exceptions.py│
       │ Validation │ │ 🇹🇿 Data     │ │ Error        │
       │ & Schemas  │ │ Lookup     │ │ Handling     │
       └────────────┘ └─────┬──────┘ └──────────────┘
                            │
                            ▼
                 ┌────────────────────┐
                 │ Tanzania Location   │
                 │      Data          │
                 ├────────────────────┤
                 │ Region             │
                 │ City               │
                 │ District           │
                 └─────────┬──────────┘
                           │
                           ▼
                ┌─────────────────────────┐
                │       API Response      │
                │                         │
                │ Pincode → Region        │
                │         → City          │
                │         → District      │
                └─────────────────────────┘

emtaa/
│
├── main.py             # FastAPI application and API routes
├── models.py           # Pydantic request/response models
├── data.py             # Pincode and location data
├── exceptions.py       # Custom exceptions and handlers
├── requirements.txt    # Python dependencies
├── Scripts/            # Virtual environment scripts
├── .gitignore
└── README.md

🚀 Getting Started

1. Clone the repository

git clone https://github.com/Ibrahist/emtaa.git
cd emtaa

2. Create a virtual environment

Windows

python -m venv emtaa

Activate it:

emtaa\Scripts\activate

macOS / Linux

python3 -m venv emtaa
source emtaa/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Start the API

uvicorn main:app --reload

The API will normally be available at:

http://127.0.0.1:8000

📚 API Documentation

Once the server is running, FastAPI automatically provides interactive documentation.

Swagger UI

http://127.0.0.1:8000/docs

ReDoc

http://127.0.0.1:8000/redoc

🔌 API Endpoints

GET /

Returns a welcome message.

Example

GET /

Response

{
  "message": "Welcome to the Pincode lookup API!"
}

---

GET /pincode/{code}

Look up a location using a 6-digit pincode.

Example

GET /pincode/123456

Response

{
  "pincode": "123456",
  "region": "Dar es Salaam",
  "city": "Dar es Salaam",
  "district": "Ilala"
}

Validation

Pincodes must:

• Contain exactly 6 digits
• Exist in the available pincode dataset

Invalid or unknown pincodes return an appropriate error response.

---

POST /pincodes

Look up multiple pincodes in a single request.

Request

{
  "pincodes": ["123456", "654321", "111111"]
}

Response

{
  "status": "success",
  "found": 3,
  "not_found": 0,
  "results": [
    {
      "pincode": "123456",
      "region": "Dar es Salaam",
      "city": "Dar es Salaam",
      "district": "Ilala"
    }
  ],
  "missing": []
}

The bulk endpoint accepts up to 10 pincodes per request.

🗺️ Current Sample Data

The project currently includes sample pincode mappings for locations including:

Pincode	Region	City	District
123456	Dar es Salaam	Dar es Salaam	Ilala
654321	Mwanza	Mwanza	Mwanza
111111	Arusha	Arusha	Arusha
222222	Dodoma	Dodoma	Dodoma
333333	Mbeya	Mbeya	Mbeya
444444	Kilimanjaro	Moshi	Moshi
555555	Tanga	Tanga	Tanga
666666	Zanzibar	Zanzibar City	Zanzibar

Note: These are currently sample/test records. For production use, the dataset should be replaced or expanded with verified Tanzanian postal-code data.

🛒 Example Checkout Use Case

The API can be integrated into an e-commerce checkout flow:

Customer enters pincode
        ↓
Frontend sends pincode to API
        ↓
GET /pincode/{code}
        ↓
API returns region, city & district
        ↓
Checkout form automatically fills location

This can reduce manual address entry and improve the checkout experience.

🧪 Testing with cURL

Single lookup

curl http://127.0.0.1:8000/pincode/123456

Bulk lookup

curl -X POST http://127.0.0.1:8000/pincodes \
  -H "Content-Type: application/json" \
  -d "{\"pincodes\":[\"123456\",\"654321\",\"111111\"]}"

🔐 Production Considerations

Before using the API in production, consider:

• Replacing sample pincode data with verified postal data
• Adding API authentication if required
• Adding rate limiting
• Adding logging and monitoring
• Deploying behind HTTPS
• Adding automated tests
• Moving location data from an in-memory dictionary to a database for larger datasets
• Adding CORS configuration for frontend applications
• Adding proper deployment configuration

🔮 Future Improvements

The project is considered 100% complete in its current scope. Future releases may introduce additional capabilities such as:

• Add complete Tanzanian postal-code dataset
• Add database support
• Add automated tests
• Add CORS configuration
• Add API authentication
• Add rate limiting
• Add Docker support
• Add deployment configuration
• Add API versioning
• Add search by region, city, or district
• Add frontend checkout demo

🤝 Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch

git checkout -b feature/my-feature

3. Make your changes
4. Commit your changes

git add .
git commit -m "Add my feature"

5. Push your branch

git push origin feature/my-feature

6. Open a Pull Request

📄 License

This project is currently available without a specified license.

If you intend to distribute or accept external contributions, consider adding an appropriate open-source license.

👨‍💻 Author

Ibrahist

GitHub: https://github.com/Ibrahist

⭐ Support

If you find this project useful, consider giving the repository a ⭐ on GitHub.

---

❌ Data Disclaimer

The data provided are auto-generated for testing purposes only. I accept no responsibility for the authenticity or accuracy of the provided data.