Grid System State

Returns South African grid system state data for the given time range. Supports hourly (1h) and daily (1d) intervals. Requires API key authentication.

GET /api/v1/grid/system-state

Get grid system state (authenticated)

cURL

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

200

{
  "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).

Response

200

application/json

meta · object · required

Show child attributes

data · object[] · required

Show child attributes