Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/beyarkay/eskom-calendar

Get your loadshedding schedule in your calendar and never be left in the dark! Open-source, up-to-date, and developer friendly.
https://github.com/beyarkay/eskom-calendar

api calendar csv eskom ics loadshedding rust schedule south-africa southafrica

Last synced: 3 months ago
JSON representation

Get your loadshedding schedule in your calendar and never be left in the dark! Open-source, up-to-date, and developer friendly.

Awesome Lists containing this project

README 

        


  


    

      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](#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](https://github.com/beyarkay) 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](https://creativecommons.org/licenses/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](https://stackoverflow.blog/2009/06/25/attribution-required/) 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](https://googleblog.blogspot.com/2005/01/preventing-comment-spam.html).



## 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](https://eskom-calendar-api.shuttleapp.rs/)



> 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](https://github.com/beyarkay/eskom-calendar-api) ❤️



Thanks to the folks at [shuttle.rs](https://www.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`](https://github.com/beyarkay/eskom-calendar/releases/download/latest/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)

```sh

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

```sh

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

```sh

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](https://stackoverflow.com/a/60671292/14555505)

if you get an SSL error)



```python

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](https://sepush.co.za/), 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](https://img.shields.io/badge/all_contributors-7-orange.svg?style=flat-square)](#contributors-)



[Boyd Kane](https://github.com/beyarkay) is the creator and maintainer. Reach out

on [twitter](https://twitter.com/beyarkay) if you want to chat in private, otherwise

[open an issue](https://github.com/beyarkay/eskom-calendar/issues/new)!



  

    

      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`](https://github.com/beyarkay/eskom-calendar/blob/main/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:



- 

    Support on Ko-Fi

  

- 

    Support on Patreon