# City Power — 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.

> Check real-time loadshedding schedules, outage status, and electricity tariffs for Johannesburg, plus access customer service information, billing details, and company news. Plan your power usage with loadshedding schedules and stay updated on City Power's latest announcements, FAQs, and contact information.

**Category:** Government & Public Data | **Website:** [citypower.co.za/](https://citypower.co.za/) | **Docs:** [parse.bot/marketplace/2a850a83-d12e-4fc1-a501-25d2b0c65024/citypower-co-za-api](https://parse.bot/marketplace/2a850a83-d12e-4fc1-a501-25d2b0c65024/citypower-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/city-power/`
**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 company reports

Retrieve links to company reports and financial statements, organized by report category (Annual Reports, Annual Financial Statements, Business Plans, Quarterly Reports, etc.) and financial year.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-company-reports \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get contact info

Retrieve City Power contact details including service delivery centre addresses with map links, telephone numbers, query-specific contacts with operating hours, and general contacts.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-contact-info \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get customer relations info

Get general customer service resources including document links and meter reading schedules with submission instructions.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-customer-relations-info \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get faq

Retrieve all frequently asked questions and answers, categorized by FAQ type (Tariffs, General, SSEG). Each FAQ includes the question, answer paragraphs, category, and optional document link.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-faq \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get homepage status

Get homepage overview including company statistics, values, quick links, and current loadshedding alerts. Combines multiple data sources into a single dashboard view.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-homepage-status \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get latest news

Retrieve the latest news articles and press releases from City Power. Each article includes the headline, story paragraphs, author, and publication date.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-latest-news \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get loadshedding planner

Search for loadshedding schedules for a specific suburb. Returns all areas, the full timetable, and matched areas filtered by the suburb name. Useful for finding which loadshedding block a specific area belongs to.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `suburb` | string | No | Suburb or area name to search for (case-insensitive partial match). Omitting returns all areas with an empty matched_areas array. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-loadshedding-planner \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"suburb":"<string>"}'
```

### Get loadshedding schedule

Retrieve the full loadshedding timetable with time ranges per block/stage/day, and area-to-block mappings. Each timetable entry specifies which block is affected at which time, day, and stage.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-loadshedding-schedule \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get loadshedding status

Get current loadshedding status (active stage) and any urgent notifications. Returns null for active_stage and notifications when no loadshedding is active.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-loadshedding-status \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get meter reading schedules

Retrieve the meter reading schedule information including submission instructions, email contacts, and document links for step-by-step guides.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-meter-reading-schedules \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get outages status

Retrieve current active outages and faults reported across the network, grouped by outage type (planned and unplanned). Each outage includes affected areas, date, region, and substation.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-outages-status \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get prepaid vending info

Get information about prepaid electricity vending and purchasing options including vendor names, logos, and links to purchase platforms.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-prepaid-vending-info \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get sseg info

Get information about Small Scale Embedded Generation (SSEG) and solar feed-in, filtered from the FAQ database. Returns only FAQ entries categorized as SSEG.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-sseg-info \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get tariffs and charges

Retrieve current electricity tariff structures including residential, commercial, and industrial rates, plus links to tariff documents. Tariffs are grouped by type (RESIDENTIAL, BUSINESS, LARGE_POWER_USERS) with seasonal pricing blocks.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-tariffs-and-charges \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get tender bulletins

List current and past tenders issued by City Power with bid documents, specifications, closing dates, and contact information.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/city-power/get-tender-bulletins \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## 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.