Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openelectricity.org.au/llms.txt

Use this file to discover all available pages before exploring further.

The Open Electricity API exposes time-series data for the NEM and WEM networks at multiple intervals: 5-minute (interval), hourly (hour), daily (day), weekly (week), monthly (month), quarterly (quarter), seasonal (season), and yearly (year). The 5-minute interval is the source resolution — every longer interval is aggregated from those 5-minute records. How a metric aggregates depends on whether it is a rate (e.g. power in MW — an instantaneous measurement) or a quantity (e.g. energy in MWh — accumulated over an interval).
  • Rates aggregate with averaging. Twelve 5-minute power readings, averaged, give the average power over the hour.
  • Quantities aggregate with summing. Twelve 5-minute energy values, summed, give the total energy in the hour.
This page lists every metric returned by the API along with its unit, type, and per-interval aggregation rule.

​
Generation data — /v4/data/network/{network_code} and /v4/data/facilities/{network_code}

MetricUnitType5-min sourceAggregation (hour+)
powerMWRateunit_intervals.generatedAverage of source values over the interval
energyMWhQuantityunit_intervals.energySum of source values
emissionstCO₂Quantityunit_intervals.emissionsSum of source values
market_valueAUDQuantityunit_intervals.market_valueSum of source values
storage_batteryMWhRate (state of charge)unit_intervals.energy_storageAverage of source values

​
Aggregation details

  • Hourly (hour) queries read from the 5-minute base table (unit_intervals) and apply avg() or sum() directly across the twelve 5-minute records in each hour.
  • Daily and longer (day, week, month, quarter, season, year) queries read from the daily materialised view (unit_intervals_daily_mv). The daily MV stores generated as the daily sum of 5-minute power values plus an interval_count column. For power, the API computes an interval-weighted average across the queried daily rows: 
    sum(generated) / sum(interval_count)
    This is equivalent to the average of the original 5-minute readings over the queried window, including partial first/last days where interval_count < 288.
  • energy, emissions, market_value sum across the queried daily rows directly.
  • storage_battery uses an interval-weighted average over the daily MV’s energy_storage_sum / energy_storage_count columns.

​
How 5-minute energy values are produced

Each 5-minute energy value is computed by Open Electricity from the corresponding generated (MW) readings using the trapezoidal rule (area under the power curve): 
energy_i (MWh) = (generated_i + generated_{i-1}) / 2 × Δt
where Δt is the interval length in hours (e.g. 5/60 for NEM 5-minute data). At crawl time a placeholder value of generated × Δt is written immediately so freshly-ingested intervals have a value, then the energy worker (opennem/workers/energy.py) replaces it with the trapezoidal calculation and stamps energy_quality_flag = 2. The API returns the post-worker value; it does not re-derive energy from power at query time. See the Energy guide for the full derivation and worked example.

​
Market data — /v4/market/network/{network_code}

MetricUnitTypeAggregation (hour+)
priceAUD/MWhRateInterval-weighted average
demandMWRate
demand_energyMWhQuantitySum
demand_grossMWRate
demand_gross_energyMWhQuantitySum
generation_renewableMWRate
generation_renewable_energyMWhQuantitySum
generation_renewable_with_storageMWRate
generation_renewable_with_storage_energyMWhQuantitySum
curtailmentMWRate
curtailment_solar_utilityMWRate
curtailment_windMWRate
curtailment_energyMWhQuantitySum
curtailment_solar_utility_energyMWhQuantitySum
curtailment_wind_energyMWhQuantitySum
flow_importsMWRate
flow_exportsMWRate
flow_imports_energyMWhQuantitySum
flow_exports_energyMWhQuantitySum
renewable_proportion%Ratiosum(generation_renewable) / sum(demand_gross) × 100 over the queried window
renewable_with_storage_proportion%Ratiosum(generation_renewable_with_storage) / sum(demand_gross) × 100 over the queried window

​
price aggregation

price is averaged because it is a per-MWh rate. For hourly aggregation, the API takes the simple average of the 5-minute prices in the hour. For daily and longer, it uses an interval-weighted average from the market_summary daily materialised view: sum(price_sum) / sum(price_count).

​
Proportion metrics

renewable_proportion and renewable_with_storage_proportion are ratios computed over the whole queried window per row, not averaged from the underlying 5-minute proportions. The sums of the numerator and denominator are taken first, then divided.

​
Known issues

MARKET MW metrics are currently summed across intervals, when they should be averaged. Affects: demand, demand_gross, generation_renewable, generation_renewable_with_storage, curtailment, curtailment_solar_utility, curtailment_wind, flow_imports, flow_exports on /v4/market/network/{network_code} at any interval above 5-minute.For example, requesting demand at interval=hour will return a value 12× larger than the true hourly average demand. The corresponding *_energy metric (e.g. demand_energy) is unaffected — it returns the correct total energy.Workaround: divide the returned value by the number of 5-minute intervals in the requested period (12 per hour, 288 per day, etc.).Tracked in opennem#525 (follow-up to the DATA/FACILITY fix in opennem#523). A fix is in progress — it requires restructuring the query builder to use a subquery for derived ratio metrics like renewable_proportion.
The HOUR interval on /v4/market/network/{network_code} will server-error if you request both renewable_proportion (or renewable_with_storage_proportion) and generation_renewable (or generation_renewable_with_storage, demand_gross) in the same call. This is a ClickHouse analyzer limitation that the query builder will work around once opennem#525 lands. As a workaround, request the proportion separately from the generation metrics, or use a daily/longer interval which is unaffected.

​
Generation aggregation — fully fixed

/v4/data/network/{network_code} and /v4/data/facilities/{network_code} return correct averages and sums per the table above, including for batteries (storage_battery). The behaviour was corrected in opennem#523 — prior to that fix, power was summed across 5-minute intervals which produced values 12× the true hourly average.

​
See also