Octopus Energy Free Electricity Events API

API Endpoint

GET https://matthewgall.github.io/octoevents/free_electricity.json

This API provides a comprehensive list of Octopus Energy's free electricity events, automatically updated every hour.

Data Sources

🔗 David S Kendall's API

Historical events from the maintainer of the Home Assistant Octopus Energy integration

oe-api.davidskendall.co.uk/free_electricity.json

🦄 Octopus Energy GraphQL API

Real-time event data fetched directly from Octopus Energy's official GraphQL API

api.octopus.energy/v1/graphql/

Data Format

The API returns a JSON object with a data array containing event objects:

{
  "data": [
    {
      "start": "2024-08-15T12:00:00.000Z",
      "end": "2024-08-15T13:00:00.000Z",
      "code": "1"
    },
    {
      "start": "2024-11-27T11:00:00.000Z",
      "end": "2024-11-27T12:00:00.000Z",
      "code": "9",
      "is_test": true
    }
  ]
}

Fields

start: Event start time in UTC (ISO 8601 format)
end: Event end time in UTC (ISO 8601 format)
code: Sequential integer identifier starting from 1
is_test: Optional boolean flag indicating test events

How It's Built

Go GitHub Actions GraphQL GitHub Pages YAML Config

Architecture

Data Fetching: Go application authenticates with Octopus Energy API using JWT tokens
Data Merging: Combines historical events from David Kendall's API with new events from Octopus GraphQL
Deduplication: Events are deduplicated using start+end time as unique identifiers
Sequential Coding: Events are assigned sequential integer codes for easy reference
Automated Updates: GitHub Actions runs hourly to fetch and publish new events
GitHub Pages: Data is served via GitHub Pages for high availability

🔄 Update Schedule

This data is automatically updated every hour via GitHub Actions. The service ensures:

New events are added automatically
Historical events are never deleted
Empty files are never published (fail-safe protection)
Data consistency is maintained across updates

Source Code

This service is open source and available on GitHub:

https://github.com/matthewgall/octoevents

Contributing

Issues, feature requests, and pull requests are welcome! The project is designed to be:

Reliable and fail-safe
Easy to configure and deploy
Compatible with existing integrations
Well-documented and maintainable

Acknowledgments

Special thanks to David S Kendall for maintaining the Home Assistant Octopus Energy integration and providing the original data source that inspired this project.

🔌 Octopus Energy Free Electricity Events