# Tunisian Municipality API

> Free, open-source REST API for Tunisia's administrative geography: 24 governorates, 261 delegations and 4,788 localities with 958 postal codes, Arabic and English names, and GPS coordinates.

Base URL: https://tn-municipality-api.vercel.app
No API key or authentication. Every endpoint is GET and returns JSON.
The API does not send CORS headers, so call it from server-side code (an API route, server action or backend), not directly from browser code on another domain.

Endpoints:
- GET /api/municipalities
  Returns governorates with their localities. All query parameters are optional and can be combined:
  - search: searches governorates first, then delegations if nothing matches (English or Arabic names)
  - name: governorate name, falls back to delegation search
  - delegation: delegation name, falls back to governorate search
  - postalCode: exact 4-digit postal code
  - sort: name | nameAr
  - order: asc (default) | desc
- GET /api/municipalities/near?lat={latitude}&lng={longitude}&radius={km}
  Returns only the localities within the radius, grouped by governorate.
  lat, lng and radius are all required; without them the full dataset is returned.

Response shape:
[
  {
    "Name": "ARIANA",
    "NameAr": "أريانة",
    "Value": "ARIANA",
    "Delegations": [
      {
        "Name": "ARIANA VILLE (Residence Kortoba)",
        "NameAr": "أريانة المدينة (إقامة قرطبة)",
        "Value": "ARIANA VILLE",
        "PostalCode": "2058",
        "Latitude": 36.866011,
        "Longitude": 10.193923
      }
    ]
  }
]

Notes:
- Each item in "Delegations" is a locality. Items that share the same "Value" belong to the same delegation.
- A locality's own name is the text in parentheses in "Name" and "NameAr".
- Several localities can share one postal code.

## Examples

- All data: https://tn-municipality-api.vercel.app/api/municipalities
- Search: https://tn-municipality-api.vercel.app/api/municipalities?search=ariana
- Postal code: https://tn-municipality-api.vercel.app/api/municipalities?postalCode=2058
- Sorted by Arabic name: https://tn-municipality-api.vercel.app/api/municipalities?sort=nameAr
- Nearby: https://tn-municipality-api.vercel.app/api/municipalities/near?lat=36.8065&lng=10.1815&radius=5

## Links

- Documentation and playground: https://tn-municipality-api.vercel.app
- Source code: https://github.com/youssef-of-web/tn-municipality-api