eskomlol

README

eskomlol

Eskom Loadshedding API package

eskomlol (eskom lekker ol' loadshedding)

Overview

eskomlol provides a thin wrapper around the existing Eskom API for loadshedding. This package attempts to simplify using the not-so-friendly base API. Please note that changes of the API will potentially break this package. If we don't expect Eskom to properly maintain powerstations, we probably can't expect them to maintain an API.

Usage

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/teamjorge/eskomlol"
)

func main() {
	// Creating a new client with no options
	client := eskomlol.New()

	// Creating a client with some options
	client = eskomlol.New(eskomlol.WithTimeout(60 * time.Second))

	// Get current loadshedding stage
	stage, err := client.Status(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Stage\n", stage)

    // Hopefully prints -1 or 0 :D
}

Additional calls you can make are:

• Municipalities
• Suburbs
• SearchSuburbs (Similar to Suburbs but does not require a municipality)
• Schedule

Notes

During testing I've noticed that some of the suburbs do not have schedules available. I'm not 100% sure if this is due to the municipalities not making them available or if it's just Eskom not having them. I'm not sure how ESP are sourcing their info, but I'm assuming it's via scraping. That could potentially be added later if there's demand for it.

Contributing

If you find bugs or have feature requests, don't be afraid to gooi a PR or create a new issue. I'm happy to improve this if folks are actually using it.

Documentation

Index

• type Client
  • func New(opts ...ClientOpt) *Client
  • func (c *Client) Municipalities(ctx context.Context, province Province) (Municipalities, error)
  • func (c *Client) Schedule(ctx context.Context, suburbID string, stages ...Stage) (map[Stage]Schedule, error)
  • func (c *Client) SearchSuburbs(ctx context.Context, searchTerm string, maxResults *int) (SearchSuburbs, error)
  • func (c *Client) Status(ctx context.Context) (Stage, error)
  • func (c *Client) Suburbs(ctx context.Context, municipalityID string, searchTerm string, page int) (SuburbResult, error)
• type ClientOpt
  • func WithTimeout(timeout time.Duration) ClientOpt
• type HttpClient
• type Municipalities
• type Municipality
• type Province
• type Schedule
• type ScheduleItem
• type SearchSuburb
• type SearchSuburbs
  • func (s SearchSuburbs) OmitEmpty() SearchSuburbs
• type Stage
  • func (s Stage) Name() string
  • func (s Stage) Valid() bool
• type Suburb
• type SuburbResult
• type Suburbs
  • func (s Suburbs) OmitEmpty() Suburbs

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the structure for performing requests to the Eskom API.

func New

func New(opts ...ClientOpt) *Client

New creates an instance of the Client with the given options.

The timeout is set by default to 30 seconds and can be overridden with the withTimeout option.

func (*Client) Municipalities

func (c *Client) Municipalities(ctx context.Context, province Province) (Municipalities, error)

Municipalities returns a list of municipalities that Eskom supplies to.

func (*Client) Schedule

func (c *Client) Schedule(ctx context.Context, suburbID string, stages ...Stage) (map[Stage]Schedule, error)

Schedule returns the loadshedding schedule for the given suburb and stage(s).

func (*Client) SearchSuburbs

func (c *Client) SearchSuburbs(ctx context.Context, searchTerm string, maxResults *int) (SearchSuburbs, error)

SearchSuburbs returns all suburbs that match the given searchTerm.

maxResults can be omitted (nil) if the default of 300 is acceptable.

func (*Client) Status

func (c *Client) Status(ctx context.Context) (Stage, error)

Status retrieves the current Loadshedding stage.

Values of -1 and 0 indicate no loadshedding currently.

func (*Client) Suburbs

func (c *Client) Suburbs(ctx context.Context, municipalityID string, searchTerm string, page int) (SuburbResult, error)

Suburbs returns a list of suburbs from the given municipality and search term.

The responses are paginated and can be iterated by using the page parameter. The result object contains a Total field to indicate the total number of results.

type ClientOpt

type ClientOpt func(*Client)

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOpt

WithTimeout sets the http timeout for the Client to the given duration.

type HttpClient

type HttpClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type Municipalities

type Municipalities []Municipality

type Municipality

type Municipality struct {
	ID       string `json:"Value,omitempty"`
	Name     string `json:"Text,omitempty"`
	Disabled bool   `json:"Disabled,omitempty"`
	Selected bool   `json:"Selected,omitempty"`
	Group    string `json:"Group,omitempty"`
}

type Province

type Province int

const (
	EasternCape Province = iota + 1
	FreeState
	Gauteng
	KwazuluNatal
	Limpopo
	Mpumalanga
	NorthWest
	NorthernCape
	WesternCape
)

type Schedule

type Schedule struct {
	Stage
	Times []ScheduleItem
}

Schedule represents a loadshedding schedule for specific stage.

type ScheduleItem

type ScheduleItem struct {
	Start time.Time
	End   time.Time
}

ScheduleItem represents a single instance of loadshedding.

type SearchSuburb

type SearchSuburb struct {
	MunicipalityName string `json:"MunicipalityName,omitempty"`
	ProvinceName     string `json:"ProvinceName,omitempty"`
	Name             string `json:"Name,omitempty"`
	ID               int    `json:"Id,omitempty"`
	Total            int    `json:"Total,omitempty"`
}

type SearchSuburbs

type SearchSuburbs []SearchSuburb

func (SearchSuburbs) OmitEmpty

func (s SearchSuburbs) OmitEmpty() SearchSuburbs

OmitEmpty filters for SearchSuburbs with a non-zero Total.

type Stage

type Stage int

func (Stage) Name

func (s Stage) Name() string

Name returns the descriptive name of the loadshedding stage.

func (Stage) Valid

func (s Stage) Valid() bool

Valid determines if the stage is within the valid range.

type Suburb

type Suburb struct {
	ID    string `json:"id,omitempty"`
	Name  string `json:"text,omitempty"`
	Total int    `json:"Tot,omitempty"`
}

type SuburbResult

type SuburbResult struct {
	Results Suburbs `json:"Results,omitempty"`
	Total   int     `json:"Total,omitempty"`
}

type Suburbs

type Suburbs []Suburb

func (Suburbs) OmitEmpty

func (s Suburbs) OmitEmpty() Suburbs

OmitEmpty filters for Suburbs with a non-zero Total.