Eskom APIeskom.co.za ↗
Access real-time loadshedding status, procurement tenders, electricity tariffs, media statements, and investor documents from Eskom via a single API.
What is the Eskom API?
This API exposes 9 endpoints covering Eskom South Africa's public data: current loadshedding stage via get_loadshedding_status, active procurement tenders and their downloadable documents, electricity tariff pages, media room articles, site search, Cost Estimate Letter (CEL) and IPP grid-connection documents, and investor relations PDFs. Each endpoint targets a distinct section of the Eskom website and returns structured, machine-readable fields directly usable in applications monitoring South Africa's power grid.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/162f0187-e02a-4cb8-988a-ca71cb601ed6/get_loadshedding_status' \ -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 eskom-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.
"""Walkthrough: Eskom SDK — loadshedding status, tenders, articles, tariffs."""
from parse_apis.eskom_website_api import Eskom, Query, TenderNotFound
client = Eskom()
# Check current loadshedding status — single resource fetch.
status = client.loadsheddingstatuses.get()
print(f"Loadshedding stage: {status.stage}, status: {status.status}")
# Browse active procurement tenders, capped to 5 items.
for tender in client.tenders.list(limit=5):
print(f"Tender {tender.tender_id}: {tender.reference} — {tender.province}")
# Drill into first tender's documents via sub-resource.
tender = client.tenders.list(limit=1).first()
if tender:
for doc in tender.documents.list(limit=3):
print(f" Doc: {doc.name} ({doc.size} bytes) — {doc.content_type}")
# Search articles using the Query enum.
article = client.articles.search(query=Query.LOADSHEDDING, limit=1).first()
if article:
print(f"Top result: {article.title}")
print(f" URL: {article.url}")
# Typed error handling — catch TenderNotFound on a missing tender.
try:
missing_tender = Eskom().tenders.list(limit=1).first()
if missing_tender:
_ = missing_tender.documents.list(limit=1).first()
except TenderNotFound as exc:
print(f"Tender not found: {exc.tender_id}")
# Retrieve investor relations documents.
for doc in client.investordocuments.list(limit=3):
print(f"Investor doc: {doc.title} — {doc.url}")
print("Exercised: loadsheddingstatuses.get / tenders.list / documents.list / articles.search / investordocuments.list")
Retrieve the current loadshedding status from Eskom. Returns the numeric stage level as a string. A stage of '1' means Stage 1 loadshedding is active; '-1' typically indicates no active loadshedding. The status field provides a human-readable description.
No input parameters required.
{
"type": "object",
"fields": {
"stage": "string representing the raw stage number from the API",
"status": "string indicating the current loadshedding status description"
},
"sample": {
"data": {
"stage": "1",
"status": "Stage 1"
},
"status": "success"
}
}About the Eskom API
Loadshedding and Tariff Data
get_loadshedding_status returns two fields: stage (a raw string such as '1' through '8', or '-1' when no loadshedding is active) and status (a human-readable description). No input parameters are required. For tariff information, get_current_tariffs returns the page title, an array of sections describing tariff categories, and year_links — an array of objects with text and url keys pointing to specific tariff schedule pages. Those URLs can be fed directly into get_tariff_year_page (using its required url parameter) to retrieve the title and a content array of paragraph and list-item text for each schedule page.
Procurement Tenders and CEL Documents
get_procurement_tenders returns active tender listings including REFERENCE, TENDER_ID, HEADER_DESC, SCOPE_DETAILS, CLOSING_DATE, Province, and a DOCS count. An optional tender_id filter narrows results, but only matches tenders currently in the active dataset — expired or removed tenders will not appear. get_tender_documents accepts a required tender_id and returns a list of downloadable files with ID, NAME, SIZE, ContentType, and a download_url for each. Folder-type entries (with ContentType of 'Folder' and SIZE of 0) may also appear in results.
get_cel_documents is a focused endpoint that returns two collections: tenders (tender objects pre-filtered to CEL, IPP, and renewable energy topics, each with tender_id, reference, subject, scope, and closing_date) and library_documents (objects with title and url for PDFs from the Grid Access Unit Library). This endpoint requires no inputs and is suited for independent power producers or grid-connection researchers.
Media, Search, and Investor Relations
get_media_room_articles returns paginated news listings — url, date, title, and summary (which may be null) — with an optional page integer for pagination. search_site accepts a required query string and returns matching url, title, and summary fields across the broader Eskom site. get_investor_relations_documents returns a deduplicated list of PDF links (url and title) from Eskom's integrated results page; entries with generic anchor text such as 'Read more' are excluded automatically.
The Eskom API is a managed, monitored endpoint for eskom.co.za — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when eskom.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 eskom.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?+
- Build a loadshedding alert system that polls
get_loadshedding_statusand notifies users when thestagevalue changes. - Aggregate active Eskom procurement tenders by
Provinceand surface relevant opportunities to B2B vendors. - Download and index tender documents using
get_tender_documentsto track specification changes across bid cycles. - Track published electricity tariff schedules by chaining
get_current_tariffswithget_tariff_year_pagefor eachyear_linksURL. - Monitor Eskom's media room for new press releases and statements by paginating through
get_media_room_articles. - Screen for IPP and renewable energy grid-connection tenders using the pre-filtered
tendersarray fromget_cel_documents. - Build an investor dashboard by pulling financial PDF listings from
get_investor_relations_documents.
| 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 Eskom provide an official public developer API?+
What does `get_loadshedding_status` actually return, and how do I interpret the stage value?+
get_loadshedding_status returns two fields: stage (a raw string integer such as '1', '4', or '8') and status (a description string). A stage value of '-1' indicates no active loadshedding. The endpoint takes no input parameters and always reflects the current live status.Can I retrieve expired or historical procurement tenders using `get_procurement_tenders`?+
tender_id filter only matches tenders currently in the active dataset. Expired, closed, or removed tenders will not appear in results. The API covers active tender listings and their associated documents. You can fork it on Parse and revise it to add an endpoint targeting historical tender archives if Eskom surfaces them on the site.Does the API return real-time generation or grid-capacity statistics (e.g. MW output, ESKOM System Status)?+
Is pagination supported for media room results, and can I retrieve all articles at once?+
get_media_room_articles supports an optional page integer parameter for pagination. Each call returns one page of results as displayed on the Eskom Media Room. There is no bulk endpoint that returns all articles in a single response; iterate over page numbers to collect larger sets.