Loadshedding schedules in your digital calendar. No apps, no ads, up-to-date, and developer friendly.
Get it • Key Features • Using the API • Project goals & alternatives • Website & API uptimeGo to eskomcalendar.co.za and just type in your area! No apps, no adverts, no nonsense. If you want more information, keep reading.
| Creator of EskomSePush | SAfm |
|---|---|
|
|
| Good Things Guy | Stellenbosch University |
|
|
eskom-calendar makes planning around loadshedding as easy as it gets. Subscribe to the digital calendar for your area, and you'll see loadshedding in your schedule on your phone, laptop, smartwatch, smartfridge, alles. We'll show you loadshedding as far into the furture as Eskom allows us.
Many loadshedding apps don't actually tell you when your lights are off, or if they do, it's difficult to find or only shows you the very next power outage. eskom-calendar shows you all the times your lights will be off, right in your digital calendar.
If you're a team manager, add the calendars for your team members and know exactly when everyone will go dark so you don't have someone dropping off in the middle of a meeting.
Businesses can see loadshedding schedules for all their branches in one view, and prepare accordingly.
IT departments can automate turning on generators or shutting down servers (see Using the Data in Your Own Projects).
eskom-calendar does one thing, and does it well. You get an event in your calendar if your power is going to go off, and that's it. There's no adverts, there's no bloat. Just loadshedding information. Doesn't get simpler than that, does it?
eskom-calendar was created by Boyd Kane because there was no way for a casual coder to just get loadshedding information programmatically without messing with API keys and whatnot.
To the best of our knowledge, this is the easiest way to automate away the pain of loadshedding, and it's the only open-source option to provide the times when power will be off, as opposed to just the loadshedding schedule for any given area (please get in contact if I'm wrong!, would be great to collab).
The data (CSV and ICS files) are available under the CC BY-NC-SA 4.0 license. This means that
You are free to:
Share: copy and redistribute the material in any medium or format
Adapt: remix, transform, and build upon the material
But only if you follow the following terms:
Attribution: You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
NonCommercial: You may not use the material for commercial purposes.
ShareAlike: If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
No additional restrictions: You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
Attribution should be done in a form similar to how StackOverflow requires it. Specifically:
-
Visually indicate that the content is from EskomCalendar in some way. It doesn’t have to be obnoxious; a discreet text blurb is fine.
-
When a specific calendar is being used, you must hyperlink directly to the website's version of that calendar (for example, https://eskomcalendar.co.za/ec?calendar=city-of-cape-town.ics). You do not have to present the full URL to the user, so long as it is clear that it is an EskomCalendar URL.
-
If no specific calendar is being used, or the
machine_friendly.csvfile is being used, you must either hyperlink directly to the project website (https://eskomcalendar.co.za) or directly to the project github page (https://github.com/beyarkay/eskom-calendar)
By directly, we mean each hyperlink must point directly to the specified URL in standard HTML visible even with JavaScript disabled, and not use a tinyurl or any other form of obfuscation or redirection. Furthermore, the links must not be nofollowed.
We are really interested to see what the developers of South Africa do with this data source. Go view the api here
Hey! The API is version 0.0.1, so might still have some rough edges. That said, it does have all the data you'd want for regular usage and should already be stable enough for hobby projects. If you find a problem or have a suggestion, please open an issue on the API repo ❤️
Thanks to the folks at shuttle.rs for powering the backend! Honestly it probably wouldn't have happened without their free tier.
As a quick preview, the API lets you get the times when Stellenbosch will be out of power with a simple get request:
curl https://eskom-calendar-api.shuttleapp.rs/outages/western-cape-stellenbosch | jq
[
{
"area_name": "western-cape-stellenbosch",
"stage": 6,
"start": "2023-06-01T18:00:00+02:00",
"finsh": "2023-06-01T20:30:00+02:00",
"source": "https://twitter.com/Eskom_SA/status/1664250326818365440"
},
...
]
Go check it out! It's free and unrestricted.
(This method has been replaced by the API, and isn't as nice to use as the API.)
The main file of interest will be
machine_friendly.csv
built from the same source of information as the calendar files. It looks
something like:
│ File: machine_friendly.csv
───────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1 │ area_name,start,finsh,stage,source
2 │ kwazulu-natal-mpofana,2022-09-25T23:00:00+02:00,2022-09-26T01:30:00+02:00,3,"https://twitter.com/Eskom_SA/status/1574014612097454080"
3 │ kwazulu-natal-mpofana,2022-09-26T07:00:00+02:00,2022-09-26T09:30:00+02:00,3,"https://twitter.com/Eskom_SA/status/1574014612097454080"
4 │ kwazulu-natal-mpofana,2022-09-26T16:00:00+02:00,2022-09-26T17:30:00+02:00,4,"https://twitter.com/Eskom_SA/status/1574014612097454080"
and you can just curl the file to get ahold of it. So go wild! DDoS Github if
you want to 😉. There are plenty of ideas floating around and I'd love to see
more. Note that the header is finsh, not finish (so that it lines up
nicely with start)
curl -sL https://github.com/beyarkay/eskom-calendar/releases/download/latest/machine_friendly.csv
area_name,stage,start,finsh,source
free-state-seretse,4,2022-09-10T10:00:00+02:00,2022-09-10T12:30:00+02:00,"https://twitter.com/Eskom_SA/status/1568494585113976835"
free-state-seretse,4,2022-09-10T18:00:00+02:00,2022-09-10T20:30:00+02:00,"https://twitter.com/Eskom_SA/status/1568494585113976835"
...curl -sL https://github.com/beyarkay/eskom-calendar/releases/download/latest/machine_friendly.csv \
| grep stellenbosch
western-cape-stellenbosch,4,2022-09-10T14:00:00+02:00,2022-09-10T16:30:00+02:00,"https://twitter.com/Eskom_SA/status/1568494585113976835"
western-cape-stellenbosch,4,2022-09-10T22:00:00+02:00,2022-09-11T00:30:00+02:00,"https://twitter.com/Eskom_SA/status/1568494585113976835"
...curl -sL https://github.com/beyarkay/eskom-calendar/releases/download/latest/machine_friendly.csv \
| grep cape-town-area-15 \
| grep 2022-09-11
city-of-cape-town-area-15,4,2022-09-11T00:00:00+02:00,2022-09-11T02:30:00+02:00,"https://twitter.com/Eskom_SA/status/1568494585113976835"
city-of-cape-town-area-15,4,2022-09-11T08:00:00+02:00,2022-09-11T10:30:00+02:00,"https://twitter.com/Eskom_SA/status/1568494585113976835"
...(mac users you might need this if you get an SSL error)
import pandas as pd
url = "https://github.com/beyarkay/eskom-calendar/releases/download/latest/machine_friendly.csv"
df = pd.read_csv(url, parse_dates=['start', 'finsh'])Feel free to open a PR with any other snippets or languages you think of!
eskom-calendar tries to achieve the following goals:
- Be open-source, easy to integrate with, and encouraging of new ideas
- Provide an accesible information source for loadshedding in South Africa
- Be dead simple to use
eskom-calendar does not try to:
- Solve every solution itself. It embraces the Unix philosophy of
do one thing, and do it well. Calendars are provided as an example of what's possible, but the heart of it is the open-source data with which websites, apps, bots, automations, etc, can be built. - Compete. eskom-calendar tries to be the best product for users, but chasing "competitors" is distracting at best, pointless at worst.
The best known alternative would be EskomSePush, but the author didn't want another app, and wanted to see the whole loadshedding schedule at a glance. Hence eskom-calendar was born (making it open source was just the default).
Boyd Kane is the creator and maintainer. Reach out on twitter if you want to chat in private, otherwise open an issue!
 Boyd Kane |
 Shaun 🚧 |
 cliffbattco 🚧 |
 Carl Combrinck 🐛 |
 Luc Hayward 🐛 |
 Aidan Horn 🚧 |
 Declan FitzPatrick 🔣 🚧 |
Please see CONTRIBUTING.md.
This project is funded by vibes and good words at the moment. If you like what I do, or you use the project commercially, please consider supporting me:
