# Municipalities — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Find comprehensive information about South African municipalities including their financial performance, service delivery metrics, contact details, and employment data all in one place. Search across provinces, access municipal tenders and job vacancies, and explore demographic and resource information for any municipality.

**Category:** Government & Public Data | **Website:** [municipalities.co.za/](https://municipalities.co.za/) | **Docs:** [parse.bot/marketplace/59631c2b-326c-4d58-8064-1bff98d99c83/municipalities-co-za-api](https://parse.bot/marketplace/59631c2b-326c-4d58-8064-1bff98d99c83/municipalities-co-za-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_municipality_contacts

Returns contact details for a municipality organized by section (e.g. 'Contact Details', 'Resident Queries'). Each section contains entries keyed by label (e.g. 'Tel', 'Web') with a value and optional URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `municipality_id` | string | Yes | Municipality ID (from list_municipalities_by_province or search_municipalities). |
| `municipality_slug` | string | Yes | Municipality slug (from list_municipalities_by_province or search_municipalities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/get_municipality_contacts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"municipality_id":"<string>","municipality_slug":"<string>"}'
```

### get_municipality_demographic

Returns demographic data for a municipality including age structure, population growth, labour market, education levels, and household dynamics across census years.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `municipality_id` | string | Yes | Municipality ID (from list_municipalities_by_province or search_municipalities). |
| `municipality_slug` | string | Yes | Municipality slug (from list_municipalities_by_province or search_municipalities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/get_municipality_demographic \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"municipality_id":"<string>","municipality_slug":"<string>"}'
```

### get_municipality_employment

Returns employment and staffing data for a municipality across multiple years including employee costs, total positions, vacancies, and managerial positions.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `municipality_id` | string | Yes | Municipality ID (from list_municipalities_by_province or search_municipalities). |
| `municipality_slug` | string | Yes | Municipality slug (from list_municipalities_by_province or search_municipalities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/get_municipality_employment \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"municipality_id":"<string>","municipality_slug":"<string>"}'
```

### get_municipality_financial

Returns multi-year financial data for a municipality including revenue, expenditure, capital sources, financial position, and cash flows. Data is structured as tables with headers (year columns) and rows (section, label, values).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `municipality_id` | string | Yes | Municipality ID (from list_municipalities_by_province or search_municipalities). |
| `municipality_slug` | string | Yes | Municipality slug (from list_municipalities_by_province or search_municipalities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/get_municipality_financial \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"municipality_id":"<string>","municipality_slug":"<string>"}'
```

### get_municipality_management

Returns leadership and management information for a municipality including council composition, mayor, municipal manager, CFO, and senior management. Each entry has a role and names (string for single, array for multiple persons).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `municipality_id` | string | Yes | Municipality ID (from list_municipalities_by_province or search_municipalities). |
| `municipality_slug` | string | Yes | Municipality slug (from list_municipalities_by_province or search_municipalities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/get_municipality_management \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"municipality_id":"<string>","municipality_slug":"<string>"}'
```

### get_municipality_overview

Returns the general overview for a municipality: official name, description, area, cities/towns, and main economic sectors. The details object contains key-value pairs scraped from the overview page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `municipality_id` | string | Yes | Municipality ID (from list_municipalities_by_province or search_municipalities). |
| `municipality_slug` | string | Yes | Municipality slug (from list_municipalities_by_province or search_municipalities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/get_municipality_overview \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"municipality_id":"<string>","municipality_slug":"<string>"}'
```

### get_municipality_resources

Returns official document links (Annual Reports, Audited Financial Statements, Audit Reports, IDPs) for a municipality. Each entry has a title and URL pointing to a PDF on treasury.gov.za.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `municipality_id` | string | Yes | Municipality ID (from list_municipalities_by_province or search_municipalities). |
| `municipality_slug` | string | Yes | Municipality slug (from list_municipalities_by_province or search_municipalities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/get_municipality_resources \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"municipality_id":"<string>","municipality_slug":"<string>"}'
```

### get_municipality_services

Returns service delivery statistics (water, electricity, sewerage, solid waste) across multiple years for a municipality. Data is structured as tables with headers (year columns) and rows grouped by service type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `municipality_id` | string | Yes | Municipality ID (from list_municipalities_by_province or search_municipalities). |
| `municipality_slug` | string | Yes | Municipality slug (from list_municipalities_by_province or search_municipalities). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/get_municipality_services \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"municipality_id":"<string>","municipality_slug":"<string>"}'
```

### list_municipal_tenders

Returns municipalities within a province and their tender page links. Each entry includes the municipality name, a link to their official tender page (if available), and a link to view tenders on TenderAlerts.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `province_id` | string | No | Province ID (1 through 9). Defaults to 1 (Eastern Cape). |
| `province_slug` | string | No | Province slug. Defaults to 'eastern-cape'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/list_municipal_tenders \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"province_id":"<string>","province_slug":"<string>"}'
```

### list_municipal_vacancies

Returns municipalities within a province and their vacancies page links. Each entry includes the municipality name and a URL to their official vacancies page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `province_id` | string | No | Province ID (1 through 9). Defaults to 1 (Eastern Cape). |
| `province_slug` | string | No | Province slug. Defaults to 'eastern-cape'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/list_municipal_vacancies \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"province_id":"<string>","province_slug":"<string>"}'
```

### list_municipalities_by_province

Returns all municipalities (metropolitan, district, and local) within a specific province. Each result includes an ID and slug usable for drill-down endpoints (overview, contacts, financial, etc.).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `province_id` | string | Yes | Province ID (1 through 9). Obtain from list_provinces. |
| `province_slug` | string | Yes | Province slug (e.g. 'eastern-cape', 'gauteng', 'kwazulu-natal'). Obtain from list_provinces. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/list_municipalities_by_province \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"province_id":"<string>","province_slug":"<string>"}'
```

### list_provinces

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.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/list_provinces \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_municipalities

Full-text search across municipality names, towns, and persons. Returns matching municipalities with IDs and slugs for drill-down. Results may include duplicates when a term matches multiple pages for the same municipality.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `term` | string | Yes | Search keyword (e.g. 'cape town', 'johannesburg', 'ekurhuleni'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-municipalities-co-za-api-59631c2b/search_municipalities \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"<string>"}'
```