> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.isoview.io/llms.txt. > For full documentation content, see https://docs.isoview.io/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.isoview.io/_mcp/server. # 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. All timeseries data uses the period-beginning convention. This is in contrast to the common "hour ending" convention often used by ISOs. ### Structure ```json { "model": "optimized", "created_at": "2026-03-17T06:00:00Z", "units": "MW", "timezone": "America/Chicago", "time_utc": [ "2026-03-17T07:00:00Z", "2026-03-17T08:00:00Z", "2026-03-17T09:00:00Z" ], "time_local": [ "2026-03-17T01:00:00-06:00", "2026-03-17T02:00:00-06:00", "2026-03-17T03:00:00-06:00" ], "columns": [ ["ercot_total"], ["ercot_north"] ], "values": [ [45230.5, 44890.1, 44520.8], [18200.3, 17950.7, 17800.2] ] } ``` ### Fields | Field | Type | Description | | ------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | `string \| null` | Weather model used for this forecast (e.g., `optimized`, `iso`, `normal`). Null for historical actuals. | | `created_at` | `string \| null` | UTC timestamp when the forecast was created/published. Represents the time the forecast was generated. Null for continuous forecasts or historical actuals. | | `units` | `string` | Measurement units for all data values. Common values: `MW`, `°C`, `USD/MWh`, `$/MMBtu`. | | `timezone` | `string` | IANA timezone identifier used for the `time_local` field (e.g., `America/New_York`, `America/Chicago`). Selected based on operating timezone of the ISO. | | `time_utc` | `string[]` | Array of UTC timestamps. Each entry corresponds to one position in each series inside `values`. | | `time_local` | `string[]` | Array of local timestamps (timezone specified in `timezone` field). Parallel to `time_utc`. | | `columns` | `string[][]` | Metadata describing each series in the `values` matrix. Each entry is a list of one or more level labels — single-level columns are returned as length-1 sublists (e.g., `["pjm_total"]`); naturally multi-level data uses one entry per level. The **summary** endpoint returns `[target_id, metric, region_type, kind]` because it mixes heterogeneous series (e.g., `forecast` and `actual`); the **ensemble** endpoint returns `[target_id, member_index]` to distinguish ensemble members (e.g., `["pjm_total", "0"]`, `["pjm_total", "1"]`). Clients can rebuild a pandas `MultiIndex` via `pd.MultiIndex.from_tuples(columns)`. | | `values` | `number[][]` | 2D matrix of numeric values. The outer index matches `columns` — `values[j]` is the full timeseries for `columns[j]`. The inner index matches `time_utc`. Missing data is represented as `null`. | ### 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: | | `ercot_total` | `ercot_north` | | ---------------------- | ------------- | ------------- | | `2026-03-17T07:00:00Z` | 45230.5 | 18200.3 | | `2026-03-17T08:00:00Z` | 44890.1 | 17950.7 | | `2026-03-17T09:00:00Z` | 44520.8 | 17800.2 | ### Working with the `TimeSeriesResponse` The response structure makes it easy to convert directly to a pandas DataFrame. ```python import requests import pandas as pd response = requests.get( "https://api.isoview.io/v1/region/ercot/demand/forecast?id=ercot_total", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = response.json() # Convert to a pandas DataFrame df = pd.DataFrame( data["values"], columns=pd.to_datetime(data["time_utc"]), index=pd.MultiIndex.from_tuples(data["columns"]), ).T print(f"Model: {data['model']}") print(f"Units: {data['units']}") 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 | Metric | Units | Description | | ------------ | --------- | -------------------------------------------------- | | `demand` | `MW` | Electricity demand in megawatts | | `wind` | `MW` | Wind generation capacity in megawatts | | `solar` | `MW` | Solar generation capacity in megawatts | | `outage` | `MW` | Generation outages in megawatts | | `poptemp` | `°C` | Population-weighted temperature in degrees Celsius | | `dalmp` | `USD/MWh` | Day-ahead locational marginal price | | `rtlmp` | `USD/MWh` | Real-time locational marginal price | | `wind_icing` | `%` | Wind icing risk coverage percentage (0–100) | | `solar_snow` | `%` | Solar snow/ice risk coverage percentage (0–100) | | `gas` | `$/MMBtu` | Natural gas price per million BTU |