Skip to content

Latest commit

 

History

History
361 lines (291 loc) · 18.1 KB

README.md

File metadata and controls

361 lines (291 loc) · 18.1 KB
Raw

eskom-calendar: loadshedding in your calendar

GitHub downloads GitHub Repo stars Twitter share Discord Eskom-calendar API Health
Support on Ko-Fi Support on Patreon

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 uptime

How to Get It

Go to eskomcalendar.co.za and just type in your area! No apps, no adverts, no nonsense. If you want more information, keep reading.

Testimonials

Creator of EskomSePush SAfm
Good Things Guy Stellenbosch University

Key Features

Easy to understand and plan around

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.

An event in your calendar means your lights are off

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.

Perfect for teams and businesses

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

No adverts

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?

The only open source, automation friendly option

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

Attribution and using the data (commercially or otherwise)

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.csv file 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.

Using the API

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.

curl-ing the raw github data

(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)

Simply download the CSV via curl (-s to be silent, -L to follow redirects)

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

Get all data for a specific area

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

Get all data for a certain day in a certain area

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

Get the file in Python

(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!

Project Goals and Alternatives

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

Contributors

All Contributors

Boyd Kane is the creator and maintainer. Reach out on twitter if you want to chat in private, otherwise open an issue!

Boyd Kane
Boyd Kane
⚠️ 💻 🐛 📖 🚧		 Shaun
Shaun
🚧		 cliffbattco
cliffbattco
🚧		 Carl Combrinck
Carl Combrinck
🐛		 Luc Hayward
Luc Hayward
🐛		 Aidan Horn
Aidan Horn
🚧		 Declan FitzPatrick
Declan FitzPatrick
🔣 🚧

Contributing

Please see CONTRIBUTING.md.

Support

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: