municipalities.co.za APImunicipalities.co.za ↗
Access contact details, financials, demographics, services, management, tenders, and vacancies for all South African municipalities via a structured API.
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'
Returns a list of all 9 South African provinces with their IDs, slugs, and names. No parameters required.
No input parameters required.
{
"type": "object",
"fields": {
"data": "array of province objects with id, slug, and name",
"status": "string, always 'success'"
},
"sample": {
"data": [
{
"id": "1",
"name": "Eastern Cape",
"slug": "eastern-cape"
},
{
"id": "3",
"name": "Gauteng",
"slug": "gauteng"
}
],
"status": "success"
}
}About the municipalities.co.za 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.
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.
- 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 | 250 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.