municipalities APImunicipalities.co.za ↗
Access contact details, financials, demographics, services, management, tenders, and vacancies for all South African municipalities via a structured API.
What is the municipalities API?
The municipalities.co.za API covers all 9 South African provinces and their municipalities across 13 endpoints, returning structured data on finances, service delivery, demographics, employment, and leadership. The get_municipality_financial endpoint alone returns multi-year revenue, expenditure, capital, and cash-flow tables. Other endpoints such as get_municipality_management and list_municipal_tenders surface council composition and official tender page links for every municipality.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/ecf986bc-1114-4a3a-81a9-57931656afec/list_provinces' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace municipalities-co-za-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Municipalities of South Africa SDK — bounded, re-runnable."""
from parse_apis.municipalities_of_south_africa_api import (
Municipalities, ProvinceSlug, MunicipalityNotFound
)
client = Municipalities()
# List all provinces and pick Gauteng by its slug.
for province in client.provinces.list(limit=9):
print(province.name, province.slug)
# Search for a municipality by keyword, take the first result.
munic = client.municipalitysummaries.search(term="cape town", limit=1).first()
if munic:
# Drill into overview — typed fields.
overview = munic.overview()
print(overview.name, overview.description)
for key, val in overview.details.items():
print(f" {key}: {val}")
# Get management entries for this municipality.
for entry in munic.management(limit=3):
print(entry.role, entry.names)
# Navigate from province → sub-resources (tenders, vacancies).
gauteng = client.provinces.list(limit=9).first()
if gauteng:
for tender in gauteng.tenders.list(limit=3):
print(tender.municipality, tender.municipality_tender_url)
# Typed error handling around a municipality detail call.
if munic:
try:
financials = munic.financial()
for table in financials.tables[:1]:
for row in table.rows[:2]:
print(row.section, row.label, row.values)
except MunicipalityNotFound as exc:
print(f"Municipality gone: {exc.municipality_id}")
print("exercised: provinces.list / search / overview / management / tenders.list / financial")
Returns all 9 South African provinces with their IDs, slugs, and names. Static data — no network call required. Use province IDs and slugs to drill into municipalities via list_municipalities_by_province.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of province objects with id, slug, and name"
},
"sample": {
"data": {
"items": [
{
"id": "1",
"name": "Eastern Cape",
"slug": "eastern-cape"
},
{
"id": "3",
"name": "Gauteng",
"slug": "gauteng"
},
{
"id": "9",
"name": "Western Cape",
"slug": "western-cape"
}
]
},
"status": "success"
}
}About the municipalities API
Province and Municipality Discovery
Start with list_provinces to retrieve all 9 province objects, each with an id, slug, and name. Pass a province_id and province_slug to list_municipalities_by_province to get the full list of metropolitan, district, and local municipalities in that province. The search_municipalities endpoint accepts a free-text term and returns matching municipality objects with their IDs and slugs, which serve as required inputs to every detail endpoint.
Municipality Detail Endpoints
get_municipality_overview returns a description and key-value detail pairs covering area, cities and towns, and main economic sectors. get_municipality_contacts organises contact entries by section (e.g. Contact Details, Resident Queries), each with a value and an optional url. get_municipality_management returns an array of role-and-names objects covering the mayor, municipal manager, senior management, and council composition — names may be a single string or an array depending on the role.
Structured Data Tables
Several endpoints return a tables array where each table carries headers (column names or census years) and rows (each with section, label, and year-keyed values). This structure applies to get_municipality_financial (revenue, expenditure, financial position, cash flows), get_municipality_services (water, electricity, sewerage, solid waste across multiple years), get_municipality_demographic (age structure, population growth, labour market, education), and get_municipality_employment (employee costs, total positions, vacancies, managerial headcount).
Tenders, Vacancies, and Official Documents
list_municipal_tenders and list_municipal_vacancies both accept optional province_id or province_slug filters and return link arrays pointing to each municipality's official tender or vacancies page. get_municipality_resources returns direct URLs to PDF documents — Annual Reports, AFS, and IDPs — hosted on treasury.gov.za.
The municipalities API is a managed, monitored endpoint for municipalities.co.za — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when municipalities.co.za changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official municipalities.co.za API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate multi-year financial performance across municipalities for public finance research using
get_municipality_financial. - Build a municipal tender aggregator by collecting official tender page URLs from
list_municipal_tendersprovince by province. - Map service delivery coverage (water, electricity, sewerage) over time using the tables returned by
get_municipality_services. - Populate a government contact directory with addresses, phone numbers, and emails from
get_municipality_contacts. - Track leadership changes across municipalities by periodically calling
get_municipality_managementand comparing mayor and manager names. - Display census-year demographic comparisons — population growth, age structure, labour market — using
get_municipality_demographic. - Surface municipal job listings by collecting vacancy page links from
list_municipal_vacanciesfiltered by province.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does municipalities.co.za have an official developer API?+
What does `get_municipality_financial` return, and how many years of data are included?+
get_municipality_financial returns a tables array covering revenue, expenditure, capital budgets, financial position, and cash flows. Each table has column headers representing financial years and rows keyed by section and label. The number of years present depends on what municipalities.co.za has on record for each municipality and varies by entity.Do the tender and vacancy endpoints return the actual tender or vacancy listings, or just links?+
list_municipal_tenders returns each municipality's name, a municipality_tender_url pointing to its official tender page (or null if unavailable), and a view_tenders_url linking to TenderAlerts. list_municipal_vacancies returns a vacancies_url per municipality. Neither endpoint returns individual tender or vacancy records directly. You can fork the API on Parse and revise it to add endpoints that follow those URLs and return the underlying listings.Is ward-level or sub-municipal geographic data available?+
get_municipality_overview, but does not expose ward boundaries, ward councillor data, or GIS geometries. You can fork the API on Parse and revise it to add the missing endpoint.How should I look up a municipality if I only know the town name rather than the municipality name?+
search_municipalities with a term matching the town or city name. The endpoint searches across municipalities and associated towns, returning matching objects with id and slug values that can be passed directly to any detail endpoint.