Transmission operational timeseries

Query half-hourly flow, rating and headroom timeseries for transmission lines.

POSThttps://api.renewmap.com.au/api/v1/network/transmission/timeseries/points

Requires API key in Authorization header. See Getting started for authentication details.

Body parameters

Name	Type	Description
series*	string[]	One or more transmission series, each as "name" or "name:rollup". See the series table below
from*	integer	Start of the range in epoch milliseconds, inclusive
to*	integer	End of the range in epoch milliseconds, exclusive. Must be greater than from
interval*	enum	Bucket size. One of "hh", "d", "w", "m" or "y"
entity_ids*	string[]	RenewMap infrastructure ids for transmission lines, maximum 500
time_of_day_intervals	integer[]	Half-hour slots of the day, 1 to 48. Returns a value per bucket per slot

Example request

curl --request POST \
  --url 'https://api.renewmap.com.au/api/v1/network/transmission/timeseries/points' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
  "series": ["line_headroom_thermal", "line_rating_norm"],
  "from": 1735689600000,
  "to": 1738368000000,
  "interval": "d",
  "entity_ids": ["a921a3fa-ab4a-41a7-ac7e-754b3b831fbf"]
}'

Example response

{
  "from": 1735689600000,
  "to": 1738368000000,
  "interval": "d",
  "data": [
    {
      "entity_id": "a921a3fa-ab4a-41a7-ac7e-754b3b831fbf",
      "series": "line_headroom_thermal",
      "rollup": "avg",
      "key": "Tarong to Halys",
      "value": 812.4,
      "timestamp": "2025-01-01T00:00:00.000Z"
    },
    {
      "entity_id": "a921a3fa-ab4a-41a7-ac7e-754b3b831fbf",
      "series": "line_rating_norm",
      "rollup": "avg",
      "key": "Tarong to Halys",
      "value": 1043.0,
      "timestamp": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Experimental: The operational insights endpoints are in early access.

Returns the half-hourly flow, rating and headroom timeseries that power the charts in a transmission line’s Operational tab and the headroom map visualisations, bucketed to the interval you ask for. For projects, see Project operational timeseries.

Points are ordered by entity, series and time.

Access

This endpoint requires the Operational Insights add-on on your organisation’s licence, in addition to an API key. Requests without a key return 401, and requests from an organisation without the add-on return 403. Contact [email protected] to enable it.

Authentication is the same as the rest of the API. See Getting started.

Identifying lines

entity_ids is required. These are the id values returned by Get network infrastructure for transmission lines. Any field outside the table above is rejected, so duids and project series are not accepted here; query projects through /projects/timeseries/points instead.

Series

Transmission line series are derived from every measurement point on the line and returned once per line, keyed by the line’s infrastructure name.

Name	Unit	Rollups	Description
`line_flow_mva_pos`	MVA	`avg`	Flow in the line’s primary direction. See Line Flow
`line_flow_mva_neg`	MVA	`avg`	Counter-flow, as a positive magnitude
`line_flow_mw_pos`	MW	`avg`	Real power flow in the line’s primary direction
`line_flow_mw_neg`	MW	`avg`	Real power counter-flow, as a positive magnitude
`line_rating_norm`	MVA	`avg`	Normal (continuous) rating, taken as the smallest rating across the line’s measurement points. See Ratings & Thermal Headroom
`line_rating_emer`	MVA	`avg`	Emergency rating, on the same basis
`line_headroom_thermal`	MVA	`avg`	Rating less total flow. Falls back to MW where MVA is not measured
`line_headroom_constrained`	MVA	`avg`	Headroom after thermal network constraints taken into account. See Constrained Headroom

Both flow directions can carry a value in the same period, because flow reversed within it. Add them together for the total load on the line, which is what the headroom series use.

Requesting a name outside this list returns 400 with the list of accepted series in the message.

Rollups

A series entry may carry a rollup after a colon, as "line_rating_norm:avg". Every transmission series accepts avg only, which is also the default, so the colon form changes nothing here. Flows, ratings and headroom are instantaneous MVA and MW readings, and a total of them is not a meaningful figure. Any other rollup returns 400.

Each point reports its rollup in the rollup field. Project series support sum as well; see Project operational timeseries.

Response

Field	Description
`from`, `to`	The requested range, echoed back
`interval`	The interval the response was built at, which may be coarser than the one you requested
`time_of_day_intervals`	The requested slots, echoed back. Omitted when the request did not include them
`data[].entity_id`	The infrastructure id the value belongs to
`data[].series`	The series name, without the rollup
`data[].rollup`	The rollup the value was built with, named or defaulted
`data[].key`	The line’s infrastructure name
`data[].value`	The value, in the unit of the series
`data[].timestamp`	Start of the bucket
`data[].half_hour`	The half-hour slot, `1` to `48`. Present only when `time_of_day_intervals` was requested

Lines and periods with no data are absent from data rather than returned as null, so an empty data array is a normal response for a line that reports no telemetry.

Adding time_of_day_intervals returns a point per bucket per requested half-hour slot, each carrying both a timestamp and a half_hour. This answers questions like “what is this line’s headroom during the evening peak”. Slots with no reading for a bucket are omitted, so a bucket can carry fewer points than the number of slots you requested.

How values are aggregated

Every value is an average of the half-hourly readings it covers, the only rollup these series accept. A daily line_headroom_thermal value is the average headroom across that day, not its minimum, so a short period of congestion is smoothed away at coarse intervals. Request hh over a narrower range to see it.

Averages are recombined from stored sums and counts rather than averaged again, so a bucket with missing readings is not weighted incorrectly.

Timestamps

All timestamps and half-hour slots are in market time: Australian Eastern Standard Time (UTC+10), with no daylight saving adjustment all year. Slot 1 is 00:00 to 00:30 and slot 48 is 23:30 to 00:00. See Data sources & coverage.

Limits

Maximum 500 entity_ids per request
A response is capped at roughly 5,000 buckets. When the range and interval you asked for would exceed that, the endpoint steps the interval up (hh to d, then w, m, y) until the request fits, and returns the interval it actually used in the interval field. A year of hh data comes back as d. Read interval from the response rather than assuming your request was honoured, and page through shorter ranges to keep half-hourly resolution over a long period
Requests are rate limited per organisation. Exceeding the limit returns 429. See Getting started

Errors

Status	Meaning
`400`	The body is not valid JSON, a field failed validation, an unrecognised field or series rollup was supplied, or `entity_ids` was missing
`401`	Missing or invalid API key
`403`	The organisation does not hold the Operational Insights add-on
`429`	Rate limit exceeded

Error responses carry a JSON body with a message field. Validation failures are joined into a single message, so one response can describe several problems.

Product

Solutions

Company

Resources