City Power APIcitypower.co.za ↗
Access City Power Johannesburg electricity tariffs, loadshedding schedules, outages, news, FAQs, and contact info via a single structured API.
What is the City Power API?
The City Power API exposes 15 endpoints covering everything from real-time loadshedding status and suburb-level schedule lookups to electricity tariffs, active network outages, tender bulletins, and customer contact details. Endpoints like get_loadshedding_planner let you filter schedules by suburb name, while get_outages_status returns grouped fault data with affected areas, regions, and substation identifiers — all as structured JSON ready to consume.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/33668489-22a5-4e1d-8ff4-bd1051a06f02/get_tariffs_and_charges' \ -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 citypower-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.
"""
City Power Johannesburg API - Usage Example
Get your API key from: https://parse.bot/settings
"""
from parse_apis.city_power_johannesburg_api import (
CityPower,
NotFoundError_,
)
client = CityPower()
# Check current loadshedding status.
status = client.loadsheddingstatuses.get()
print(f"Loadshedding active stage: {status.active_stage}")
# List current outages across the network — planned and unplanned.
for category in client.outagecategories.list(limit=5):
print(category.name, f"({len(category.outages)} active outages)")
for outage in category.outages[:2]:
print(f" {outage.outage_date} - {outage.substation} ({outage.region})")
# Browse the latest news articles from City Power.
article = client.newsarticles.list(limit=1).first()
if article:
print(article.subject, article.published_date)
# Search loadshedding planner for a specific suburb.
plan = client.loadsheddingplans.search(suburb="Sandton")
print(f"Matched areas: {len(plan.matched_areas)}, Total areas: {len(plan.all_areas)}")
# List current tenders with closing dates and bid documents.
tender = client.tenders.list(limit=1).first()
if tender:
try:
print(tender.name, tender.closing_date, f"({len(tender.bid_documents)} docs)")
except NotFoundError_ as exc:
print(f"tender not found: {exc}")
# Browse company reports organised by financial year.
for report_cat in client.reportcategories.list(limit=3):
print(report_cat.reportpage, f"- {len(report_cat.finyears)} financial years")
print("exercised: loadsheddingstatuses.get / outagecategories.list / newsarticles.list / loadsheddingplans.search / tenders.list / reportcategories.list")
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.
No input parameters required.
{
"type": "object",
"fields": {
"business_tariffs": "array of business tariff objects with tariff_name, tariffs, and tariffType",
"tariff_documents": "object with page info and linksItems array of document links",
"residential_tariffs": "array of residential tariff objects with tariff_name, tariffs, and tariffType",
"large_power_users_tariffs": "array of industrial/large power user tariff objects"
},
"sample": {
"data": {
"business_tariffs": [
{
"id": 39,
"finYear": null,
"tariffs": [
{
"prepaid_id": 20,
"tarrif_season": "Summer Energy Charges",
"residentPrepaidItems": [
{
"current": "274,62",
"approved": "308,04",
"items_id": 176,
"residentialPrepaid": "Block 1(0-500kWh)"
}
]
}
],
"tariffType": "BUSINESS",
"tariff_name": "Business Prepaid"
}
],
"tariff_documents": {
"id": 3,
"page": "Tariffs",
"linksItems": [
{
"link": "",
"items_id": 12,
"link_pdf": "Customer_Services/Tariffs/2025-26 T Book-14-01-2025ppp.pdf",
"link_name": "Tariffs And Charges",
"link_image": ""
}
]
},
"residential_tariffs": [
{
"id": 31,
"finYear": null,
"tariffs": [
{
"prepaid_id": 6,
"tarrif_season": "",
"residentPrepaidItems": [
{
"current": "175,38",
"approved": "227,28",
"items_id": 108,
"residentialPrepaid": "Block 1(0-500kWh)"
}
]
}
],
"tariffType": "RESIDENTIAL",
"tariff_name": "Residential Single Phase 60A"
}
],
"large_power_users_tariffs": [
{
"id": 44,
"finYear": null,
"tariffs": [
{
"prepaid_id": 32,
"tarrif_season": "",
"residentPrepaidItems": [
{
"current": "185,32",
"approved": "238,03",
"items_id": 226,
"residentialPrepaid": "Summer Energy Charge"
}
]
}
],
"tariffType": "LARGE_POWER_USERS",
"tariff_name": "Industrial LV"
}
]
},
"status": "success"
}
}About the City Power API
Loadshedding Data
The get_loadshedding_status endpoint returns the active_stage (or null when no loadshedding is in effect) and any notifications currently in effect. For schedule detail, get_loadshedding_schedule returns a full timetable array — each entry carries blockId, timeRange, dayId, and stageId — alongside area_blocks that map area names to block IDs. get_loadshedding_planner accepts an optional suburb string and returns both all_areas and a matched_areas array filtered to that suburb, making it straightforward to build a per-neighbourhood schedule view.
Tariffs and Outages
get_tariffs_and_charges returns four top-level arrays: residential_tariffs, business_tariffs, large_power_users_tariffs, and tariff_documents. Each tariff object includes tariff_name, tariffs, and tariffType. get_outages_status returns outage categories where each item has a name (e.g. "Planned Power Outage", "UnPlanned Power Outage"), a description, and an outages array with per-event fields: affected_areas, outage_date, region, and substation.
Customer Services and Company Information
get_contact_info structures City Power contacts into three arrays: Queries (with queryname, telephone, weekdays, email), Contacts, and Addresses listing service delivery centres with addressItems. get_meter_reading_schedules returns submission instructions, an email address, downloadable files, and schedules_content paragraphs. get_faq returns all FAQ entries categorised by faqType (Tariffs, General, SSEG, and others); get_sseg_info is a focused subset returning only SSEG-category entries about solar feed-in and small-scale embedded generation.
News, Tenders, and Reports
get_latest_news returns articles as a list of objects each with subject, subtitle, story (an array of paragraph strings), news_id, and published_date in YYYY-MM-DD HH:MM:SS.S format. get_tender_bulletins exposes current and past tenders with closingDate, datePostedOn, bidDocuments, bidAdverts, and a tenderpage field distinguishing current from past. get_company_reports returns a linksItems array of report document links.
The City Power API is a managed, monitored endpoint for citypower.co.za — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when citypower.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 citypower.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?+
- Display the current loadshedding stage and urgent alerts in a home-automation dashboard using
get_loadshedding_status. - Build a suburb-specific loadshedding schedule widget by querying
get_loadshedding_plannerwith a user-supplied suburb name. - Notify customers of planned or unplanned outages in their region by polling
get_outages_statusfor new entries with matchingregionoraffected_areas. - Render a current electricity tariff comparison table for residential and business customers from
get_tariffs_and_chargesresponse fields. - Surface City Power tender opportunities in a procurement tracking tool using
get_tender_bulletinswithclosingDateandbidDocuments. - Automate meter reading reminder emails by combining schedule data from
get_meter_reading_scheduleswithemailfield values. - Index City Power FAQs and SSEG solar feed-in Q&A into a searchable knowledge base using
get_faqandget_sseg_info.
| 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 City Power have an official public developer API?+
What does `get_loadshedding_planner` return when no suburb is specified?+
suburb parameter returns all areas in the all_areas array alongside the full timetable, with matched_areas returned as an empty array. Providing a suburb string performs a case-insensitive partial match and populates matched_areas with the relevant area objects and their blockId values.Does `get_outages_status` distinguish between planned and unplanned faults?+
name field that identifies the type — for example "Planned Power Outage" or "UnPlanned Power Outage". Each category also carries an outages array with per-event fields including region, substation, affected_areas, and outage_date.Can I look up historical outage records or past loadshedding stage data?+
get_outages_status returns only currently active faults, and get_loadshedding_status returns only the live stage. Historical outage or stage-change data is not exposed. You can fork this API on Parse and revise it to add an endpoint that tracks and stores stage or outage history over time.Is prepaid token or account balance lookup available through this API?+
get_prepaid_vending_info, but individual account balances, token generation, and transaction history are not exposed. You can fork the API on Parse and revise it to add any customer-portal endpoints that become accessible.