canonical: https://jentic.com/apis/mtaa-api.herokuapp.com/mtaa-api

# Mtaa API Documentation

The Mtaa API exposes Tanzania's administrative geography as a hierarchical REST endpoint, returning regions, districts, wards, and streets for the country. Developers building Tanzanian e-commerce checkouts, government service portals, or delivery platforms use it to populate cascading address selectors that match official local divisions. The five-endpoint surface walks the country down to street level by passing each level as a path segment.

## For AI agents

Look up Tanzania's administrative geography - region, district, ward, street - through a hierarchical lookup API used to populate address selectors and validate locations.

## Scope

Does not handle geocoding to latitude and longitude, routing, or non-Tanzanian geographies - use for walking the Tanzanian administrative hierarchy only.

## Capabilities

- Retrieve every region in a country via GET /{country}
- List the districts within a Tanzanian region via GET /{country}/{region}
- List the wards within a district via GET /{country}/{region}/{district}
- List the streets within a ward via GET /{country}/{region}/{district}/{ward}
- Confirm a specific street within the full hierarchy via GET /{country}/{region}/{district}/{ward}/{street}

## Use cases

### Tanzanian Address Dropdowns at Checkout

Local e-commerce checkouts need the user to pick region, district, ward, and street rather than typing free-text. The Mtaa API returns each level as the previous one is selected, so the dropdown chain stays consistent with official Tanzanian administrative names. The hierarchy avoids spelling drift between vendors and lines up with delivery courier zone naming.

Example prompt: Call GET /tanzania to populate the region dropdown, then on selection call GET `/tanzania/{region}` for districts, `/tanzania/{region}/{district}` for wards, and `/tanzania/{region}/{district}/{ward}` for streets.

### Delivery Zone Validation for Logistics

Last-mile delivery platforms validate that a customer-supplied ward and street pair exists within a chosen district before assigning a courier. Calling /{country}/{region}/{district}/{ward}/{street} confirms the full path resolves to a real entry. Failed validation routes the address to manual review instead of dispatching a rider to a nonexistent location.

Example prompt: Call GET `/tanzania/{region}/{district}/{ward}/{street}` with the customer-supplied path and reject the order if the response is empty.

### Government Services Form Population

Public sector forms in Tanzania ask citizens to identify their location by region down to ward. Using Mtaa's hierarchy ensures the form values match the administrative records held by national agencies, which avoids reconciliation work later. The API hierarchy mirrors the official PORALG administrative structure used for elections and census data.

Example prompt: Pull GET /tanzania once per session and cache, then progressively call deeper levels as the citizen narrows their location selection.

### Agent-Driven Address Capture in Chat

An AI customer support agent confirms a Tanzanian customer's delivery address conversationally. Through Jentic the agent searches for 'list tanzania regions', then drills the hierarchy as the customer answers each clarifying question. The unauthenticated API means no credentials to manage and the agent only needs to chain four operations.

Example prompt: Search Jentic for 'list tanzania regions', call GET /tanzania, ask the user to pick one, then chain through district, ward, and street with each subsequent answer.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/{country}` | List regions in a country |
| GET | `/{country}/{region}` | List districts in a region |
| GET | `/{country}/{region}/{district}` | List wards in a district |
| GET | `/{country}/{region}/{district}/{ward}` | List streets in a ward |
| GET | `/{country}/{region}/{district}/{ward}/{street}` | Validate a specific street in the hierarchy |

## Key resources

- **Country** — Top-level entry - list of regions for a supported country
- **Region** — List of districts inside a region
- **District** — List of wards inside a district
- **Ward** — List of streets inside a ward
- **Street** — Confirmation that a specific street exists in the hierarchy

## Why Jentic

- **Setup:** Wiring the Mtaa API by hand means encoding the Tanzanian administrative hierarchy into nested path segments yourself, from country down through region, district, ward, and street. Through Jentic you install once, import the Mtaa API from the API Directory, and your agent calls it, with no credential to manage because the endpoints are unauthenticated.
- **Permission scoping:** Every operation here is a read-only lookup down the administrative hierarchy, so limit the agent to the operations it needs, such as listing regions or resolving a ward. You choose which hierarchy operations are in scope, and nothing beyond those reads is reachable.
- **Credential handling:** The Mtaa API requires no credential, so there is nothing to store, and your agent reaches only the hierarchy operations you allow. No secret ever enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list tanzania regions' or 'resolve a ward in a district', and Jentic returns the matching Mtaa operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenStreetMap API** — OpenStreetMap exposes administrative boundaries globally including Tanzania
- **Positionstack API** — Positionstack offers global forward and reverse geocoding including African addresses
- **LocationIQ API** — LocationIQ adds geocoding and routing on top of an address lookup

## FAQ

### What authentication does the Mtaa API use?

The Mtaa API is unauthenticated - every endpoint is a public GET with no key or token required. Through Jentic the agent calls the hierarchy operations directly with no credential setup.

### Can I drill from country down to street level?

Yes. The five endpoints chain by path segment - /{country}, /{country}/{region}, /{country}/{region}/{district}, /{country}/{region}/{district}/{ward}, and /{country}/{region}/{district}/{ward}/{street}. Each level returns the children at the next level.

### What are the rate limits for the Mtaa API?

The Mtaa API runs on a community Heroku deployment and applies no published rate limit, but it can sleep when idle so cold-start latency is realistic. Cache the GET /{country} and region-level responses on your side rather than hitting the API on every page render.

### How do I populate an address dropdown through Jentic?

Search Jentic for 'list tanzania regions', execute GET /tanzania, then on each user selection call the next deeper endpoint - `/tanzania/{region}`, `/tanzania/{region}/{district}`, and so on. The agent receives clean lists ready to render in dropdowns.

### Is the Mtaa API free?

Yes. The Mtaa API is an open community project hosted on Heroku and does not charge per call. Plan for occasional cold starts and consider mirroring the data locally for production use.

### Can I limit what my agent is allowed to do with the Mtaa API?

Yes. Because you run Jentic One yourself, your own rules decide which Mtaa operations the agent may call. Every operation is a read-only lookup down the Tanzanian administrative hierarchy, so you can grant only the levels you need, such as listing regions or resolving a specific ward or street, and leave the deeper lookups out of scope. Nothing beyond the reads you allow is reachable, and since the API needs no credential there is no key for the agent to hold.