# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/municipalities/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/municipalities/get-municipality-contacts \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/get-municipality-demographic \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/get-municipality-employment \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/get-municipality-financial \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/get-municipality-management \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/get-municipality-overview \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/get-municipality-resources \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/get-municipality-services \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/list-municipal-tenders \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/list-municipal-vacancies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/list-municipalities-by-province \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/list-provinces \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/municipalities/search-municipalities \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"term":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.