This is the backend for eskom-calendar's API, hosted by shuttle.rs🚀.

See the uptime and live system status here.

(This is still a WIP, but should be usable for non-critical purposes)

How to use it

Proper docs will be coming in the near future, as the API is still on version v0.0.1, but the endpoint is https://eskom-calendar-api.shuttleapp.rs/v0.0.1/. Note that you can omit the version to opt-in to the latest version of the endpoint. So https://eskom-calendar-api.shuttleapp.rs/list_areas will list all the areas according to the latest version of the API. All versions are maintained, so if your app is working fine on v0.0.1, you don't have to worry about it being deprecated/removed.

The basic layout is as follows (openAPI spec is being worked on):

List all areas

curl https://eskom-calendar-api.shuttleapp.rs/v0.0.1/list_areas

List areas matching regex

curl "https://eskom-calendar-api.shuttleapp.rs/v0.0.1/list_areas/(western|eastern)-cape"

Get times when the power will be out for an area

curl https://eskom-calendar-api.shuttleapp.rs/v0.0.1/outages/western-cape-worscester

Get the full schedule for an area

(This one's got all the correct data, but some of the niceties are still just placeholders)

curl https://eskom-calendar-api.shuttleapp.rs/v0.0.1/schedules/western-cape-worscester

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.

Contributors

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

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: