Responses

TimeseriesResponse

All forecast and historical data endpoints return a standardized TimeseriesResponse object. This format efficiently represents matrix-like timeseries data with parallel arrays for timestamps and values, optimized for client-side processing and visualization.

Structure

1
{
2
  "model": "optimized",
3
  "created_at": "2026-03-17T06:00:00Z",
4
  "units": "MW",
5
  "timezone": "America/Chicago",
6
  "time_utc": [
7
    "2026-03-17T07:00:00Z",
8
    "2026-03-17T08:00:00Z",
9
    "2026-03-17T09:00:00Z"
10
  ],
11
  "time_local": [
12
    "2026-03-17T01:00:00-06:00",
13
    "2026-03-17T02:00:00-06:00",
14
    "2026-03-17T03:00:00-06:00"
15
  ],
16
  "columns": [
17
    ["ercot_total"],
18
    ["ercot_north"]
19
  ],
20
  "values": [
21
    [45230.5, 44890.1, 44520.8],
22
    [18200.3, 17950.7, 17800.2]
23
  ]
24
}

Fields

Reading the values matrix

The values matrix is organized series-first:

• Outer index corresponds to series — values[j] is the full timeseries for columns[j]
• Inner index corresponds to timestamps — values[j][i] is the value for columns[j] at time_utc[i]

For example, given the response above:

Working with the TimeSeriesResponse

The response structure makes it easy to convert directly to a pandas DataFrame.

1
import requests
2
import pandas as pd
3
4
response = requests.get(
5
    "https://api.isoview.io/v1/region/ercot/demand/forecast?id=ercot_total",
6
    headers={"X-API-Key": "YOUR_API_KEY"},
7
)
8
data = response.json()
9
10
# Convert to a pandas DataFrame
11
df = pd.DataFrame(
12
    data["values"],
13
    columns=pd.to_datetime(data["time_utc"]),
14
    index=pd.MultiIndex.from_tuples(data["columns"]),
15
).T
16
17
print(f"Model: {data['model']}")
18
print(f"Units: {data['units']}")
19
print(df.head())

Null values

Some data points may be null in the values matrix. This occurs when:

• Data is not yet available for a future timestamp
• A specific series does not have coverage for the full time range
• The source data has gaps or reporting delays

Always handle null values in your client code when processing the response.

Units by metric