This documentation has been deprecated, but is still accessible for legacy reasons.
\nPlease find the link to the latest documentation on Gumroad -> https://eskomsepush.gumroad.com/l/api
\n* Real time status for National Loadshedding
* Real time status per Area, Upcoming Events & Schedule
* Areas Search by Text
* Areas Nearby by GPS coordinates
* User Generated Topics by approx GPS location
By accessing or using the API you agree to API License Agreement.
\nRemember
\n* Each Token (aka Licence key) is allocated a Quota (typically Daily usage); once this usage has been exceeded; requests will be blocked until quota is available
* Do not share your Token
* You should only be doing requests from a single IP (not multiple simultaneously)
* Each individual must have their own Token linked to a valid email address
* If we detect malicious behaviour or anything we deem to be untoward we will disable a token without notice or warning
* We track usage in real-time and also long term
* API users have a quota, and once this quota is used up in a period (typically daily), requests will be blocked until quota is available again
* Status & Area Information count for a single request
* Area Information has a ?test parameter; which does not count toward your quota. Use it for development!
* For free accounts: Areas Search, Areas Nearby & Topics Nearby count as 5 calls toward your request quota These don't need to be called automatically or often
* The Check Allowance can be called to check your quota used & remaining. This doesn't count against your quota.
Make sure you have the correct Area ID (using Area Nearby or Area Search); GPS based search is preferred as these are areas that EskomSePush users in that area are already using.
\nIf a schedule has changed please be in contact with us to update it. Even better; help us update it (and earn some personal quota).
\nAll valid responses will have Header Content-Type: application/json
It's important to check the HTTP status code to confirm accuracy of your response before processing it.
\nAdd the following HTTP request headers, for all requests against the API.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"⚠️⚠️ DEPRECATED DOCUMENTATION⚠️⚠️","slug":"deprecated-documentation"},{"content":"Features","slug":"features"},{"content":"🚨 Important","slug":"important"},{"content":"Responses","slug":"responses"},{"content":"Authentication","slug":"authentication"}],"owner":"1296288","collectionId":"3afe2f03-cfb3-427c-9de7-3a0dbd1a8287","publishedId":"UzQuNk3E","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"F44336"},"publishDate":"2025-12-01T14:19:08.000Z"},"item":[{"name":"Check allowance","id":"10647b8e-c839-4d56-82a2-d9a406ae4f18","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"token","value":"","type":"text"}],"url":"https://developer.sepush.co.za/business/2.0/api_allowance","description":"Check allowance allocated for token
\nNOTE: This call doesn't count towards your quota.
\nExample response:
\n{\n \"allowance\": {\n \"count\": 39,\n \"limit\": 50,\n \"type\": \"daily\"\n }\n}\n\nThe current and next loadshedding statuses for South Africa and (Optional) municipal overrides
\neskom is the National status
Other keys in the status refer to different municipalities and potential overrides from the National status; most typically present is the key for capetown
Example response:
\n{\n \"status\": {\n \"capetown\": {\n \"name\": \"Cape Town\",\n \"next_stages\": [\n {\n \"stage\": \"1\",\n \"stage_start_timestamp\": \"2022-08-08T17:00:00+02:00\"\n },\n {\n \"stage\": \"0\",\n \"stage_start_timestamp\": \"2022-08-08T22:00:00+02:00\"\n }\n ],\n \"stage\": \"0\",\n \"stage_updated\": \"2022-08-08T00:08:16.837063+02:00\"\n },\n \"eskom\": {\n \"name\": \"National\",\n \"next_stages\": [\n {\n \"stage\": \"2\",\n \"stage_start_timestamp\": \"2022-08-08T16:00:00+02:00\"\n },\n {\n \"stage\": \"0\",\n \"stage_start_timestamp\": \"2022-08-09T00:00:00+02:00\"\n }\n ],\n \"stage\": \"0\",\n \"stage_updated\": \"2022-08-08T16:12:53.725852+02:00\"\n }\n }\n}\n\nObtain the id from Area Find or Area Search and use with this request. This single request has everything you need to monitor upcoming loadshedding events for the chosen suburb.
name & region
events
A sorted list of events
\nstart & end times listing when it will be impacted by loadshedding
Will be an empty list if not impacted
\nschedule
Raw loadshedding schedule, per stage (1-8)
\nFormatted for display purposes (i.e. 20:00-22:30)
Any adjacent events have been merged into a single event (e.g. 12:00-14:30 & 14:00-16:30 become 12:00-16:30)
Note: An empty list means no events for that stage
\nNote: Some Municipalities/Regions don't have Stage 5-8 schedules (and there will be 4 records instead of 8 in this list. Stage 5 upwards you can assume Stage 4 schedule impact.
\nTesting
\nInclude the &test=current or &test=future to get SAMPLE data returned in the events. current will return a loadshedding event which is occurring right now, and future will return an event starting on the next hour.
NOTE: The schedule returned with testing data is NOT accurate data; but only for testing purposes. The area _name_ and _source_ is updated to identify that this is testing data. This _test_ request will not count towards your quota.
Example response
\n{\n \"events\": [\n {\n \"end\": \"2022-08-08T22:30:00+02:00\",\n \"note\": \"Stage 2\",\n \"start\": \"2022-08-08T20:00:00+02:00\"\n }\n ],\n \"info\": {\n \"name\": \"Sandton-WEST (4)\",\n \"region\": \"Eskom Direct, City of Johannesburg, Gauteng\"\n },\n \"schedule\": {\n \"days\": [\n {\n \"date\": \"2022-08-08\",\n \"name\": \"Monday\",\n \"stages\": [\n [],\n [\n \"20:00-22:30\"\n ],\n [\n \"12:00-14:30\",\n \"20:00-22:30\"\n ],\n [\n \"04:00-06:30\",\n \"12:00-14:30\",\n \"20:00-22:30\"\n ],\n [\n \"04:00-06:30\",\n \"12:00-14:30\",\n \"20:00-22:30\"\n ],\n [\n \"04:00-06:30\",\n \"12:00-14:30\",\n \"20:00-00:30\"\n ],\n [\n \"04:00-06:30\",\n \"12:00-16:30\",\n \"20:00-00:30\"\n ],\n [\n \"04:00-08:30\",\n \"12:00-16:30\",\n \"20:00-00:30\"\n ]\n ]\n },\n {\n \"date\": \"2022-08-09\",\n \"name\": \"Tuesday\",\n \"stages\": [\n [\n \"02:00-04:30\"\n ],\n [\n \"02:00-04:30\"\n ],\n [\n \"02:00-04:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-12:30\",\n \"18:00-22:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-14:30\",\n \"18:00-22:30\"\n ]\n ]\n },\n {\n \"date\": \"2022-08-10\",\n \"name\": \"Wednesday\",\n \"stages\": [\n [\n \"10:00-12:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-14:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-14:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-14:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-14:30\",\n \"18:00-22:30\"\n ]\n ]\n },\n {\n \"date\": \"2022-08-11\",\n \"name\": \"Thursday\",\n \"stages\": [\n [\n \"18:00-20:30\"\n ],\n [\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\",\n \"18:00-22:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-14:30\",\n \"18:00-22:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-14:30\",\n \"18:00-22:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-14:30\",\n \"18:00-22:30\"\n ]\n ]\n },\n {\n \"date\": \"2022-08-12\",\n \"name\": \"Friday\",\n \"stages\": [\n [],\n [\n \"18:00-20:30\"\n ],\n [\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\",\n \"18:00-20:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-12:30\",\n \"18:00-22:30\"\n ],\n [\n \"02:00-04:30\",\n \"10:00-14:30\",\n \"18:00-22:30\"\n ],\n [\n \"02:00-06:30\",\n \"10:00-14:30\",\n \"18:00-22:30\"\n ]\n ]\n }\n ],\n \"source\": \"https://loadshedding.eskom.co.za/\"\n }\n}\n\nFind areas based on GPS coordinates (latitude and longitude).
\nThe first area returned is typically the best choice for the coordinates - as it's closest to the GPS coordinates provided. However it could be that you are in the second or third area.
\nExample response:
\n{\n \"areas\": [\n {\n \"count\": -1,\n \"id\": \"eskde-10-magaliessigext17cityofjohannesburggauteng\",\n \"name\": \"Magaliessig Ext 17 (10)\",\n \"region\": \"Eskom Direct, City of Johannesburg, Gauteng\"\n },\n {\n \"count\": -1,\n \"id\": \"eskde-10-magaliessigext1cityofjohannesburggauteng\",\n \"name\": \"Magaliessig Ext 1 (10)\",\n \"region\": \"Eskom Direct, City of Johannesburg, Gauteng\"\n },\n {\n \"count\": -1,\n \"id\": \"eskde-10-magaliessigext24cityofjohannesburggauteng\",\n \"name\": \"Magaliessig Ext 24 (10)\",\n \"region\": \"Eskom Direct, City of Johannesburg, Gauteng\"\n },\n {\n \"count\": -1,\n \"id\": \"eskde-10-magaliessigext28cityofjohannesburggauteng\",\n \"name\": \"Magaliessig Ext 28 (10)\",\n \"region\": \"Eskom Direct, City of Johannesburg, Gauteng\"\n },\n ]\n}\n\nLatitude
\n","type":"text/plain"},"key":"lat","value":"-26.0269658"},{"description":{"content":"Longitude
\n","type":"text/plain"},"key":"lon","value":"28.0137339"}],"variable":[]}},"response":[],"_postman_id":"4a9eeeb8-87c2-4088-8236-1ed3626e271d"},{"name":"Areas Search (Text)","id":"1986b098-ad88-436c-a5cd-5aa406e2fcf2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"token","value":"","type":"text"}],"url":"https://developer.sepush.co.za/business/2.0/areas_search?text=fourways","description":"Search area based on text
\nExample response:
\n{\n \"areas\": [\n {\n \"id\": \"westerncape-2-stellenboschmunicipality\",\n \"name\": \"Stellenbosch Municipality (2)\",\n \"region\": \"Western Cape\"\n },\n {\n \"id\": \"westerncape-8-stellenboschfarmers\",\n \"name\": \"Stellenbosch farmers (8)\",\n \"region\": \"Western Cape\"\n },\n {\n \"id\": \"eskomdirect-5215-stellenboschpart1outlyingstellenboschwesterncape\",\n \"name\": \"Stellenbosch Part 1 Outlying\",\n \"region\": \"Eskom Direct (Web), Stellenbosch, Western Cape\"\n },\n {\n \"id\": \"eskde-4-stellenboschnucityofcapetownwesterncape\",\n \"name\": \"Stellenbosch NU (4)\",\n \"region\": \"Eskom Direct, City of Cape Town, Western Cape\"\n },\n {\n \"id\": \"eskde-4-stellenboschnustellenboschwesterncape\",\n \"name\": \"Stellenbosch NU (4)\",\n \"region\": \"Eskom Direct, Stellenbosch, Western Cape\"\n },\n {\n \"id\": \"eskde-8-stellenboschnustellenboschwesterncape\",\n \"name\": \"Stellenbosch NU (8)\",\n \"region\": \"Eskom Direct, Stellenbosch, Western Cape\"\n },\n {\n \"id\": \"eskde-15-stellenboschnucityofcapetownwesterncape\",\n \"name\": \"Stellenbosch NU (15)\",\n \"region\": \"Eskom Direct, City of Cape Town, Western Cape\"\n },\n {\n \"id\": \"eskde-15-stellenboschnustellenboschwesterncape\",\n \"name\": \"Stellenbosch NU (15)\",\n \"region\": \"Eskom Direct, Stellenbosch, Western Cape\"\n },\n {\n \"id\": \"eskde-16-stellenboschmohokarefreestate\",\n \"name\": \"Stellenbosch (16)\",\n \"region\": \"Eskom Direct, Mohokare, Free State\"\n },\n {\n \"id\": \"eskde-16-stellenboschnustellenboschwesterncape\",\n \"name\": \"Stellenbosch NU (16)\",\n \"region\": \"Eskom Direct, Stellenbosch, Western Cape\"\n },\n {\n \"id\": \"eskde-16-stellengiftdrakensteinwesterncape\",\n \"name\": \"Stellengift (16)\",\n \"region\": \"Eskom Direct, Drakenstein, Western Cape\"\n },\n {\n \"id\": \"eskdo-5-stellenboschvleibeaufortwestwesterncape\",\n \"name\": \"Stellenboschvlei (5)\",\n \"region\": \"Eskom Direct, Beaufort West, Western Cape\"\n },\n {\n \"id\": \"eskdo-9-stellenhofsundaysrivervalleyeasterncape\",\n \"name\": \"Stellenhof (9)\",\n \"region\": \"Eskom Direct, Sundays River Valley, Eastern Cape\"\n },\n {\n \"id\": \"westerncape-2-universityofstellenbosch\",\n \"name\": \"University of Stellenbosch (2)\",\n \"region\": \"Western Cape\"\n }\n ]\n}\n\nString to search for
\n","type":"text/plain"},"key":"text","value":"fourways"}],"variable":[]}},"response":[],"_postman_id":"1986b098-ad88-436c-a5cd-5aa406e2fcf2"},{"name":"[Deprecated] Topics Nearby","id":"6d6cdae8-64d5-4d03-ab49-d3fa87031cac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"token","value":"","type":"text"}],"url":"https://developer.sepush.co.za/business/2.0/topics_nearby?lat=-33.912&lon=18.408","description":"25 October 2024: DEPRECATED
\nFind topics created by users based on GPS coordinates (latitude and longitude). Can use this to detect if there is a potential outage/problem nearby.
\nExample response:
\n{\n \"topics\": [\n {\n \"active\": \"2022-08-08T13:02:04.776000+02:00\",\n \"body\": \"Is anyone else still off in Parkhurst? According to the city power Twitter page electricity has been restored but we’re out on 11th\",\n \"category\": \"electricity\",\n \"distance\": 4.83,\n \"followers\": 1,\n \"timestamp\": \"2022-08-08T13:02:04.776000+02:00\"\n },\n {\n \"active\": \"2022-08-08T10:08:32.229000+02:00\",\n \"body\": \"Anyone selling laptops\",\n \"category\": \"information\",\n \"distance\": 3.48,\n \"followers\": 3,\n \"timestamp\": \"2022-08-07T10:43:25.319000+02:00\"\n },\n {\n \"active\": \"2022-08-08T10:02:52.791000+02:00\",\n \"body\": \"Hi , if anyone is in need of a dog sitter / baby sitter I am very flexible and able to travel. I live around the area \\nContact me on x \\nMy name is \",\n \"category\": \"information\",\n \"distance\": 1.8,\n \"followers\": 3,\n \"timestamp\": \"2022-08-08T09:48:02.819000+02:00\"\n }\n ]\n}\n\nLatitude
\n","type":"text/plain"},"key":"lat","value":"-33.912"},{"description":{"content":"Longitude
\n","type":"text/plain"},"key":"lon","value":"18.408"}],"variable":[]}},"response":[],"_postman_id":"6d6cdae8-64d5-4d03-ab49-d3fa87031cac"},{"name":"(Beta) Posts Nearby","id":"31193c62-8fd5-4823-9810-5c67e4b443bd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"token","value":"","type":"text"}],"url":"https://developer.sepush.co.za/business/2.0/posts_nearby?area_id=jhbcitypower3-2-parkhurst","description":"Find posts created by users based on the area. Can use this to detect if there is a potential outage/problem nearby, or just interesting conversations happening the area.
\n⚠️ NOTE: This endpoint is in BETA and is subject to change without notice ⚠️ Be in touch if you identify a use case where you'd like a resilient endpoint.
\nExample response:
\n{\n \"topics\": [\n {\n \"active\": \"2025-01-19T18:57:15.989000+02:00\",\n \"body\": \"There is a house alarm that has been going off intermittently in 17th street just below 1st ave for the past 2 days. Does anyone know which house number it is and which security company?\",\n \"category\": \"safety\",\n \"timestamp\": \"2025-01-19T18:03:39.407000+02:00\",\n \"title\": \"Annoying Alarm Alert!\",\n \"url\": \"https://go.esp.info/post?id=8zXVXUdQlrY4OrQCZW8y\"\n },\n {\n \"active\": \"2025-01-16T12:59:58.789000+02:00\",\n \"body\": \"Water out on first avenue west ? Any other parties experiencing this?\",\n \"category\": \"water\",\n \"timestamp\": \"2025-01-16T07:02:16.590000+02:00\",\n \"title\": \"Water Outages on First Avenue West\",\n \"url\": \"https://go.esp.info/post?id=zepL2YfujiiHHlnLbbjX\"\n }\n ]\n}\n\nArea ID
\n","type":"text/plain"},"key":"area_id","value":"jhbcitypower3-2-parkhurst"}],"variable":[]}},"response":[],"_postman_id":"31193c62-8fd5-4823-9810-5c67e4b443bd"}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"token"},{"key":"value","value":""}]}},"event":[{"listen":"prerequest","script":{"id":"a08c34fc-808a-4646-a1d3-bc8da4508638","type":"text/javascript","requests":{},"exec":[""]}},{"listen":"test","script":{"id":"27b184c1-c271-44d3-b851-ea474d0b08cc","type":"text/javascript","requests":{},"exec":[""]}}],"variable":[{"key":"URL","value":"https://developer.sepush.co.za/business/2.0"},{"key":"esp_token","value":""}]}