Grid System State

Get grid system state (authenticated)

curl --request GET \
  --url https://api.powersignals.co.za/api/v1/grid/system-state \
  --header 'X-API-KEY: <api-key>'

{
  "meta": {
    "interval": "1h",
    "derived": true,
    "start": "<string>",
    "end": "<string>",
    "dataset": "grid.system_state",
    "timezone": "UTC",
    "schema_version": "1.0"
  },
  "data": [
    {}
  ]
}

GET

api

grid

system-state

Get grid system state (authenticated)

curl --request GET \
  --url https://api.powersignals.co.za/api/v1/grid/system-state \
  --header 'X-API-KEY: <api-key>'

{
  "meta": {
    "interval": "1h",
    "derived": true,
    "start": "<string>",
    "end": "<string>",
    "dataset": "grid.system_state",
    "timezone": "UTC",
    "schema_version": "1.0"
  },
  "data": [
    {}
  ]
}

Overview

Returns South African grid system state data for a given time range.. This is the primary endpoint for accessing generation mix, imports/exports, and derived grid metrics.

Use Cases

Monitor the current state of the South African power grid
Track renewable energy penetration over time
Detect OCGT ramp events (indicators of grid stress)
Build energy forecasting models with historical data

Intervals

Interval	Description
`1h`	Raw hourly readings from Eskom
`1d`	Daily aggregation (averages, max ramp events)

Data Fields (Hourly)

Each record in the data array contains:

Field	Unit	Description
`ts`	ISO-8601	Timestamp (UTC)
`residual_demand_mw`	MW	System demand minus RE generation
`residual_forecast_mw`	MW	Forecasted residual demand
`thermal_mw`	MW	Coal-fired generation
`nuclear_mw`	MW	Nuclear generation
`eskom_gas_mw`	MW	Eskom gas turbine output
`eskom_ocgt_mw`	MW	Open-cycle gas turbine output
`hydro_water_mw`	MW	Hydro generation
`wind_mw`	MW	Wind generation
`pv_mw`	MW	Solar PV generation
`total_re_mw`	MW	Total renewable generation
`imports_mw`	MW	Power imports
`exports_mw`	MW	Power exports
`net_import_mw`	MW	Imports minus exports
`renewable_share_pct`	%	Renewable % of total generation
`ocgt_ramp_mw`	MW	Hour-over-hour OCGT change
`forecast_error_mw`	MW	Actual minus forecast residual demand

Authorizations

X-API-KEY

string

header

required

Query Parameters

end

string

required

End datetime in ISO-8601 format (e.g. 2026-01-02T00:00:00Z).

interval

enum<string>

Data resolution. Defaults to 1h.

Available options:

1d,

1h

start

string

required

Start datetime in ISO-8601 format (e.g. 2026-01-01T00:00:00Z).

Getting Started

API Reference

Guides

Overview

Use Cases

Intervals

Data Fields (Hourly)

Authorizations

Query Parameters

Response

Getting Started

API Reference

Guides

Documentation Index

​Overview

​Use Cases

​Intervals

​Data Fields (Hourly)

Authorizations

Query Parameters

Response

Overview

Use Cases

Intervals

Data Fields (Hourly)