Grid Status Developers

https://docs.gridstatus.io/developers
Admin
Grid Status provides an API and developer tools for accessing and integrating with its data,...
Tokens:53,411
Snippets:268
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Common Use Cases and Examples

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Provides practical examples of how to use the API for common analytical tasks, such as comparing day-ahead and real-time forecasts, and analyzing morning forecasts.

```APIDOC
### Common Use Cases and Examples

#### 1. Day-Ahead vs Real-Time Forecast Analysis
Compare day-ahead forecasts (published ~24 hours before) with near-real-time forecasts:
**Day-ahead forecasts:**
```json
{
  "example": "curl \"https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=latest_before:-20%20hours&start_time=2024-01-01&end_time=2024-01-02&api_key=YOUR_API_KEY\""
}
```

**Near real-time forecasts:**
```json
{
  "example": "curl \"https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=latest_before:-1%20hour&start_time=2024-01-01&end_time=2024-01-02&api_key=YOUR_API_KEY\""
}
```

#### 2. Morning Forecast Analysis
Get forecasts published during morning hours (6 AM - 12 PM):
```json
{
  "example": "curl \"https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time_start=2024-01-01T06:00:00Z&publish_time_end=2024-01-01T12:00:00Z&start_time=2024-01-01&end_time=2024-01-02&api_key=YOUR_API_KEY\""
}
```
```

--------------------------------

### Install gridstatusio Python Client

Source: https://docs.gridstatus.io/developers/getting-started/python-client

Installs the gridstatusio Python client library using pip. Ensure you have Python 3.9+ installed.

```bash
pip install gridstatusio
```

--------------------------------

### Query Dataset Endpoint (cURL)

Source: https://docs.gridstatus.io/developers/api-reference/query-data

Example of how to query a dataset using the cURL command-line tool. This demonstrates a basic GET request to the /datasets/{dataset_id}/query endpoint.

```shell
GET /v1/datasets/{dataset_id}/query HTTP/1.1
Host: api.gridstatus.io
Accept: */*


```

--------------------------------

### Query Dataset Endpoint (Python)

Source: https://docs.gridstatus.io/developers/api-reference/query-data

Example of how to query a dataset using Python's requests library. This snippet demonstrates making a GET request to the API and handling the JSON response.

```python
import requests

url = "https://api.gridstatus.io/v1/datasets/{dataset_id}/query"
headers = {
    "Accept": "*/*"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")

```

--------------------------------

### Morning forecast analysis (Shell, Python)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Get forecasts published during morning hours (6 AM - 12 PM) by combining `publish_time_start` and `publish_time_end`. This example demonstrates filtering for a specific part of the day.

```shell
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time_start=2024-01-01T06:00:00Z&publish_time_end=2024-01-01T12:00:00Z&start_time=2024-01-01&end_time=2024-01-02&api_key=YOUR_API_KEY"
```

```python
client.get_dataset(
  'ercot_load_forecast_by_forecast_zone',
  publish_time_start="2024-01-01T06:00:00Z",
  publish_time_end="2024-01-01T12:00:00Z",
  start="2024-01-01",
  end="2024-01-02"
)
```

--------------------------------

### List Datasets API Endpoint Examples

Source: https://docs.gridstatus.io/developers/api-reference/dataset-metadata

Examples demonstrating how to call the Gridstatus.io API to list datasets. Supports cURL, JavaScript, and Python.

```curl
GET /v1/datasets HTTP/1.1
Host: api.gridstatus.io
Accept: */*

```

```javascript
fetch('https://api.gridstatus.io/v1/datasets', {
  method: 'GET',
  headers: {
    'Accept': '*/*',
    'Authorization': 'Bearer YOUR_API_KEY' // Or use query parameter
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

```

```python
import requests

api_key = "YOUR_API_KEY"
url = "https://api.gridstatus.io/v1/datasets"

headers = {
    "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")

```

--------------------------------

### URL encoding for offsets (Example)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Demonstrates how to URL-encode spaces in offset parameters when constructing URLs for API requests. This ensures correct interpretation of the offset values.

```text
-6 hours becomes -6%20hours
-1 day@10:30:00 becomes -1%20day@10:30:00
```

--------------------------------

### Get API Info - Python

Source: https://docs.gridstatus.io/developers/api-reference

Example of how to retrieve API information using Python. This code snippet shows how to make a GET request to the root endpoint of the Grid Status API to fetch API metadata.

```python
import requests

response = requests.get('https://api.gridstatus.io/v1/')
data = response.json()
print(data)
```

--------------------------------

### JSON Pagination Parameters Example

Source: https://docs.gridstatus.io/developers/concepts/pagination

Example of how to append pagination parameters to a request URL for offset-based pagination. This allows users to specify the desired page number and the number of rows per page.

```plaintext
?page=2&page_size=100
```

--------------------------------

### Successful JSON Response Example

Source: https://docs.gridstatus.io/developers/api-reference/query-data

An example of a successful JSON response when querying a dataset. This includes status code, data, metadata, and dataset metadata.

```json
{
  "status_code": 200,
  "data": [
    {
      "interval_start_local": "2018-04-10T00:00:00-07:00",
      "interval_start_utc": "2018-04-10T07:00:00+00:00",
      "interval_end_local": "2018-04-10T00:05:00-07:00",
      "interval_end_utc": "2018-04-10T07:05:00+00:00",
      "load": 22459
    },
    {
      "interval_start_local": "2018-04-10T00:05:00-07:00",
      "interval_start_utc": "2018-04-10T07:05:00+00:00",
      "interval_end_local": "2018-04-10T00:10:00-07:00",
      "interval_end_utc": "2018-04-10T07:10:00+00:00",
      "load": 22371
    },
    {
      "interval_start_local": "2018-04-10T00:10:00-07:00",
      "interval_start_utc": "2018-04-10T07:10:00+00:00",
      "interval_end_local": "2018-04-10T00:15:00-07:00",
      "interval_end_utc": "2018-04-10T07:15:00+00:00",
      "load": 22330
    }
  ],
  "meta": {
    "page": 1,
    "limit": 1000,
    "page_size": 100000,
    "hasNextPage": false
  },
  "dataset_metadata": {
    "id": "caiso_load",
    "name": "CAISO Load",
    "time_index_column": "interval_start_utc",
    "all_columns": [
      {
        "name": "interval_start_local",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_start_utc",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_end_local",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_end_utc",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "load",
        "type": "INTEGER",
        "is_date": false,
        "is_datetime": false,
        "is_numeric": true
      }
    ]
  }
}

```

--------------------------------

### Combine Filters Example

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Demonstrates combining publish time filters with other parameters like date ranges and column selection.

```APIDOC
## GET /v1/datasets/ercot_load_forecast_by_forecast_zone/query

### Description
Retrieves the latest forecast data for a specific date range, selecting only specific columns.

### Method
GET

### Endpoint
/v1/datasets/ercot_load_forecast_by_forecast_zone/query

### Query Parameters
- **publish_time** (string) - Required - Specifies the time window for forecasts. Example: `latest`.
- **start_time** (string) - Required - The start of the data interval. Example: `2024-01-01`.
- **end_time** (string) - Required - The end of the data interval. Example: `2024-01-02`.
- **columns** (string) - Optional - A comma-separated list of columns to include in the response. Example: `interval_start_utc,publish_time_utc,system_total`.
- **api_key** (string) - Required - Your API key for authentication.

### Request Example
```
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=latest&start_time=2024-01-01&end_time=2024-01-02&columns=interval_start_utc,publish_time_utc,system_total&api_key=YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **status_code** (integer) - The HTTP status code.
- **data** (array) - An array of forecast data objects, containing only the specified columns.
  - **interval_start_utc** (string) - The start time of the forecast interval in UTC.
  - **publish_time_utc** (string) - The time the forecast was published in UTC.
  - **system_total** (number) - Total forecasted system load.
- **meta** (object) - Metadata about the response pagination.
- **dataset_metadata** (object) - Metadata about the dataset.

#### Response Example
```json
{
  "status_code": 200,
  "data": [
    {
      "interval_start_utc": "2024-01-01T00:00:00+00:00",
      "publish_time_utc": "2023-12-31T18:30:00+00:00",
      "system_total": 44920.54003906249
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "hasNextPage": false
  },
  "dataset_metadata": {
    "publish_time_column": "publish_time_utc",
    "time_index_column": "interval_start_utc"
  }
}
```
```

--------------------------------

### Query Dataset Endpoint (JavaScript)

Source: https://docs.gridstatus.io/developers/api-reference/query-data

Example of how to query a dataset using JavaScript. This snippet shows how to make a fetch request to the API endpoint, including necessary headers.

```javascript
fetch('/v1/datasets/{dataset_id}/query', {
  method: 'GET',
  headers: {
    'Accept': '*/*'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

```

--------------------------------

### Initialize GridStatus Client (Python)

Source: https://docs.gridstatus.io/developers/concepts/recipes

Initializes the GridStatus Python client with an API key. This is a prerequisite for all other examples. The API key can be provided directly or set as an environment variable.

```python
import gridstatusio as gs
client = gs.GridStatusClient(api_key="YOUR_API_KEY")
```

--------------------------------

### Get Day-Ahead Forecasts using cURL

Source: https://docs.gridstatus.io/developers/concepts/query-parameters

This example retrieves day-ahead forecasts by using `publish_time=latest_before:-1 day`, indicating forecasts published at least one day before the operating time. It includes a date range and requires an `api_key`.

```cURL
# Get day-ahead forecasts (published at least 1 day before)
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast/query?publish_time=latest_before:-1 day&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"
```

--------------------------------

### Example Successful JSON Response

Source: https://docs.gridstatus.io/developers/api-reference/query-data

This is an example of a successful JSON response when querying the dataset endpoint. It includes the status code, the queried data array with interval details and load values, and metadata about the pagination and dataset.

```json
{
  "status_code": 200,
  "data": [
    {
      "interval_start_local": "2018-04-10T00:00:00-07:00",
      "interval_start_utc": "2018-04-10T07:00:00+00:00",
      "interval_end_local": "2018-04-10T00:05:00-07:00",
      "interval_end_utc": "2018-04-10T07:05:00+00:00",
      "load": 22459
    },
    {
      "interval_start_local": "2018-04-10T00:05:00-07:00",
      "interval_start_utc": "2018-04-10T07:05:00+00:00",
      "interval_end_local": "2018-04-10T00:10:00-07:00",
      "interval_end_utc": "2018-04-10T07:10:00+00:00",
      "load": 22371
    },
    {
      "interval_start_local": "2018-04-10T00:10:00-07:00",
      "interval_start_utc": "2018-04-10T07:10:00+00:00",
      "interval_end_local": "2018-04-10T00:15:00-07:00",
      "interval_end_utc": "2018-04-10T07:15:00+00:00",
      "load": 22330
    }
  ],
  "meta": {
    "page": 1,
    "limit": 1000,
    "page_size": 100000,
    "hasNextPage": false
  },
  "dataset_metadata": {
    "id": "caiso_load",
    "name": "CAISO Load",
    "time_index_column": "interval_start_utc",
    "all_columns": [
      {
        "name": "interval_start_local",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      },
      {
        "name": "interval_start_utc",
        "type": "TIMESTAMP",
        "is_date": false,
        "is_datetime": true,
        "is_numeric": false
      }
    ]
  }
}
```

--------------------------------

### Get API Info - JavaScript

Source: https://docs.gridstatus.io/developers/api-reference

Example of how to retrieve API information using JavaScript. This code snippet demonstrates a fetch request to the root endpoint of the Grid Status API to obtain API details.

```javascript
fetch('https://api.gridstatus.io/v1/')
  .then(response => response.json())
  .then(data => console.log(data));
```

--------------------------------

### API Response Data Structure

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Example of a successful API response, including data, metadata, and dataset-specific information. The `publish_time_utc` column is crucial for verifying publication timing.

```JSON
{
  "status_code": 200,
  "data": [
    {
      "interval_start_utc": "2024-01-01T00:00:00+00:00",
      "interval_end_utc": "2024-01-01T01:00:00+00:00",
      "publish_time_utc": "2023-12-31T18:30:00+00:00",
      "north": 15543.961113146968,
      "south": 11921.243918188475,
      "west": 5854.474702258297,
      "houston": 11600.86030546875,
      "system_total": 44920.54003906249
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "hasNextPage": false
  },
  "dataset_metadata": {
    "publish_time_column": "publish_time_utc",
    "time_index_column": "interval_start_utc"
  }
}
```

--------------------------------

### GET /v1/

Source: https://docs.gridstatus.io/developers/api-reference

Retrieves general information about the Grid Status API, including its name and current version.

```APIDOC
## GET /v1/

### Description
Retrieves general information about the Grid Status API, including its name and current version.

### Method
GET

### Endpoint
/v1/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
GET /v1/ HTTP/1.1
Host: api.gridstatus.io
Accept: */*
```

### Response
#### Success Response (200)
- **name** (string) - The name of the API.
- **version** (string) - The current version of the API.

#### Response Example
```json
{
  "name": "Grid Status API",
  "version": "1.3.0"
}
```
```

--------------------------------

### Query API Data with Python Client

Source: https://docs.gridstatus.io/developers/concepts/query-parameters

Example of using the Python `gridstatusio` library to query dataset, applying filters, resampling, and timezone settings programmatically.

```Python
import gridstatusio as gs

client = gs.GridStatusClient(api_key="YOUR_API_KEY")

df = client.get_dataset(
    "ercot_lmp_by_settlement_point",
    start="2026-01-01",
    end="2026-01-02",
    filter_column="location",
    filter_value="HB_HOUSTON,HB_NORTH",
    filter_operator="in",
    columns=["interval_start_utc", "location", "lmp"],
    resample_frequency="1 hour",
    resample_function="mean",
    timezone="America/Chicago",
    order="desc"
)
```

--------------------------------

### Data Structure Example - JSON

Source: https://docs.gridstatus.io/developers/api-reference/query-data

This JSON snippet illustrates the structure of data returned by the GridStatus.io API. It includes fields like 'name', 'type', and boolean flags indicating date, datetime, and numeric properties for each data point.

```json
{
  "fields": [
    {
      "name": "interval_start_local",
      "type": "TIMESTAMP",
      "is_date": false,
      "is_datetime": true,
      "is_numeric": false
    },
    {
      "name": "interval_start_utc",
      "type": "TIMESTAMP",
      "is_date": false,
      "is_datetime": true,
      "is_numeric": false
    },
    {
      "name": "interval_end_local",
      "type": "TIMESTAMP",
      "is_date": false,
      "is_datetime": true,
      "is_numeric": false
    },
    {
      "name": "interval_end_utc",
      "type": "TIMESTAMP",
      "is_date": false,
      "is_datetime": true,
      "is_numeric": false
    },
    {
      "name": "load",
      "type": "INTEGER",
      "is_date": false,
      "is_datetime": false,
      "is_numeric": true
    }
  ]
}
```

--------------------------------

### Get Historical Data Snapshot (Shell/Python)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Retrieve the most recent data as it was available at a specific point in time. This is useful for historical analysis and auditing. Requires an API key for authentication.

```Shell
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=2024-07-01T00:30:00Z&start_time=2024-07-01&end_time=2024-07-02&api_key=YOUR_API_KEY"
```

```Python
client.get_dataset(
  'ercot_load_forecast_by_forecast_zone',
  publish_time="2024-07-01T00:30:00Z",
  start="2024-07-01",
  end="2024-07-02"
)
```

--------------------------------

### Filter data by start publish time (Shell, Python)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Filter records published on or after a specific timestamp. This parameter cannot be used with `publish_time`. The format is ISO 8601 datetime string.

```shell
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time_start=2024-01-01T00:00:00Z&start_time=2024-01-01&end_time=2024-01-02&limit=10&api_key=YOUR_API_KEY"
```

```python
client.get_dataset(
  'ercot_load_forecast_by_forecast_zone',
  publish_time_start="2024-01-01T00:00:00Z",
  start="2024-01-01",
  end="2024-01-02",
  limit=10
)
```

--------------------------------

### Get API Info (cURL)

Source: https://docs.gridstatus.io/developers/api-reference/api-info

This snippet shows how to retrieve basic API information from the root endpoint using cURL. It demonstrates the necessary HTTP method, host, and accept headers.

```bash
GET /v1/ HTTP/1.1
Host: api.gridstatus.io
Accept: */*

```

--------------------------------

### Get API Info - cURL

Source: https://docs.gridstatus.io/developers/api-reference

Example of how to retrieve API information using cURL. This request targets the root endpoint of the Grid Status API to get general information about the API, such as its name and version.

```shell
GET /v1/ HTTP/1.1
Host: api.gridstatus.io
Accept: */*
```

--------------------------------

### Get Latest Forecasts using cURL

Source: https://docs.gridstatus.io/developers/concepts/query-parameters

This example retrieves the most recent forecast for each hour using `publish_time=latest`. It also specifies a date range with `start_time` and `end_time`, and requires an `api_key`.

```cURL
# Get the most recent forecast for each hour
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast/query?publish_time=latest&start_time=2026-01-01&end_time=2026-01-02&api_key=YOUR_API_KEY"
```

--------------------------------

### Get Latest Data Point using cURL

Source: https://docs.gridstatus.io/developers/concepts/query-parameters

This example shows how to retrieve the most recent data point available for a dataset using the `time=latest` parameter. An `api_key` is necessary for the request.

```cURL
# Get latest data
curl "https://api.gridstatus.io/v1/datasets/ercot_fuel_mix/query?time=latest&api_key=YOUR_API_KEY"
```

--------------------------------

### Cursor Pagination Initialization

Source: https://docs.gridstatus.io/developers/concepts/pagination

Demonstrates how to initiate cursor pagination for the first request by providing an empty cursor parameter. Subsequent requests will use the cursor value obtained from the previous response's meta data.

```plaintext
cursor=""
```

--------------------------------

### Set Limits for Data Volume Control (Python)

Source: https://docs.gridstatus.io/developers/concepts/best-practices

Demonstrates how to use the 'limit' parameter in the Python client to control data volume and costs, especially during development, to prevent accidental large queries.

```python
# Always set a limit during development
data = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-01-02",
    limit=1000  # Prevent accidental large queries
)

```

--------------------------------

### Get Daily Peak Report (JavaScript)

Source: https://docs.gridstatus.io/developers/api-reference/reports

Example of fetching a daily peak report using JavaScript's fetch API. It constructs the URL with the ISO and date, and includes the API key in the headers for authentication. This method is suitable for client-side or Node.js applications.

```javascript
async function getDailyPeakReport(iso, date, apiKey) {
  const url = `https://api.gridstatus.io/v1/reports/daily_peak/${iso}?date=${date}`;
  const headers = {
    'x-api-key': apiKey
  };

  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: headers
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error fetching daily peak report:', error);
    return null;
  }
}

// Example usage:
// const apiKey = 'YOUR_API_KEY';
// getDailyPeakReport('PJM', '2025-05-16', apiKey).then(report => console.log(report));
```

--------------------------------

### Limit Result Sets (Shell/Python)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Demonstrates how to limit the number of returned records using the `limit` parameter, combined with publish time and date range filters. This is essential for managing large datasets and improving performance.

```Shell
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=window:-24%20hours&limit=1000&start_time=2024-01-01&end_time=2024-01-02&api_key=YOUR_API_KEY"
```

```Python
client.get_dataset(
  'ercot_load_forecast_by_forecast_zone',
  publish_time="window:-24 hours",
  start="2024-01-01",
  end="2024-01-02",
  limit=1000
)
```

--------------------------------

### Query Time-Series Data with Time Filters (Shell)

Source: https://docs.gridstatus.io/developers/concepts/best-practices

Demonstrates how to query time-series data efficiently by specifying 'start_time' and 'end_time'. Unbounded queries are slow and expensive, while bounded queries are fast and efficient.

```shell
# Queries entire dataset - slow and expensive
curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?api_key=YOUR_API_KEY"
```

```shell
# Bounded time range - fast and efficient
curl "https://api.gridstatus.io/v1/datasets/ercot_lmp_by_settlement_point/query?\nstart_time=2026-01-01&\nend_time=2026-01-02&\napi_key=YOUR_API_KEY"
```

--------------------------------

### Combine Publish Time with Other Filters (Shell/Python)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Illustrates combining `publish_time` filters with other query parameters like `start_time`, `end_time`, and `columns` to retrieve specific data subsets. This allows for precise data extraction.

```Shell
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=latest&start_time=2024-01-01&end_time=2024-01-02&columns=interval_start_utc,publish_time_utc,system_total&api_key=YOUR_API_KEY"
```

```Python
client.get_dataset(
  'ercot_load_forecast_by_forecast_zone',
  publish_time="latest",
  start="2024-01-01",
  end="2024-01-02",
  columns=["interval_start_utc", "publish_time_utc", "system_total"]
)
```

--------------------------------

### Get API Info (Python)

Source: https://docs.gridstatus.io/developers/api-reference/api-info

This snippet shows how to retrieve API information from the root endpoint using Python's requests library. It makes a GET request and prints the JSON response.

```python
import requests

response = requests.get('https://api.gridstatus.io/v1/')
print(response.json())
```

--------------------------------

### Analyze Forecast Revisions (Shell/Python)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Retrieve all forecasts within a 6-hour window before the operating time to analyze forecast revisions. This helps understand how predictions change over time. Requires an API key for authentication.

```Shell
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=window:-6%20hours&start_time=2024-01-01T12:00:00Z&end_time=2024-01-01T18:00:00Z&api_key=YOUR_API_KEY"
```

```Python
client.get_dataset(
  'ercot_load_forecast_by_forecast_zone',
  publish_time="window:-6 hours",
  start="2024-01-01T12:00:00Z",
  end="2024-01-01T18:00:00Z"
)
```

--------------------------------

### Query Data Within a Time Window (Shell & Python)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Fetches all forecasts published within a specific time window relative to the operating time. This allows analysis of all forecasts published in a defined period leading up to an operating time, such as the last 6 hours or from a specific time the previous day.

```shell
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=window:-6%20hours&start_time=2024-01-01&end_time=2024-01-02&limit=10&api_key=YOUR_API_KEY"
```

```python
client.get_dataset(
  'ercot_load_forecast_by_forecast_zone',
  publish_time="window:-6 hours",
  start="2024-01-01",
  end="2024-01-02",
  limit=10
)
```

--------------------------------

### Get Dataset Audit Data (HTTP)

Source: https://docs.gridstatus.io/developers/api-reference/dataset-audit

This snippet demonstrates how to make an HTTP GET request to retrieve dataset audit data. It specifies the endpoint, host, and accept headers required for the request.

```HTTP
GET /v1/datasets/{dataset_id}/audit HTTP/1.1
Host: api.gridstatus.io
Accept: */*


```

--------------------------------

### Get Dataset Metadata using Python

Source: https://docs.gridstatus.io/developers/api-reference/dataset-metadata

This Python code snippet illustrates how to retrieve dataset metadata using the `requests` library. It constructs the API URL and sends a GET request, then parses the JSON response.

```python
import requests

def get_dataset_metadata(dataset_id, api_key=None):
    url = f"https://api.gridstatus.io/v1/datasets/{dataset_id}"
    headers = {
        'Accept': 'application/json'
    }
    if api_key:
        headers['x-api-key'] = api_key

    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching dataset metadata: {e}")
        return None

# Example usage:
# metadata = get_dataset_metadata('ercot_lmp_by_bus', api_key='YOUR_API_KEY')
# if metadata:
#     print(metadata)

```

--------------------------------

### Get Dataset Metadata using cURL

Source: https://docs.gridstatus.io/developers/api-reference/dataset-metadata

This snippet demonstrates how to retrieve dataset metadata using the cURL command-line tool. It sends a GET request to the specified API endpoint, including the dataset ID in the URL.

```curl
GET /v1/datasets/{dataset_id} HTTP/1.1
Host: api.gridstatus.io
Accept: */*

```

--------------------------------

### Renewable Generation Analysis (Python)

Source: https://docs.gridstatus.io/developers/concepts/recipes

Tracks solar and wind generation patterns to understand renewable penetration trends. It fetches monthly daily average fuel mix data and calculates daily renewable metrics. Requires 'gridstatusio' and 'pandas'.

```python
import pandas as pd

# Get one month of daily fuel mix data
df = client.get_dataset(
    "ercot_fuel_mix",
    start="2026-01-01",
    end="2026-02-01",
    resample_frequency="1 day",
    resample_function="mean"
)

# Calculate daily renewable metrics
df['renewable_total'] = df['solar'] + df['wind']
df['renewable_pct'] = df['renewable_total'] / df['total'] * 100

print("=== ERCOT Renewable Generation - January 2026 ===")
print(f"\nMonthly Averages:")
print(f"  Solar: {df['solar'].mean():,.0f} MW")
print(f"  Wind: {df['wind'].mean():,.0f} MW")
print(f"  Renewable %: {df['renewable_pct'].mean():.1f}%")

print(f"\nPeak Renewable Days:")
top_renewable = df.nlargest(5, 'renewable_pct')[['interval_start_utc', 'solar', 'wind', 'renewable_pct']]
for _, row in top_renewable.iterrows():
    date = str(row['interval_start_utc'])[:10]
    print(f"  {date}: {row['renewable_pct']:.1f}% ({row['solar']:,.0f} MW solar, {row['wind']:,.0f} MW wind)")

print(f"\nLowest Renewable Days:")
low_renewable = df.nsmallest(5, 'renewable_pct')[['interval_start_utc', 'solar', 'wind', 'renewable_pct']]
for _, row in low_renewable.iterrows():
    date = str(row['interval_start_utc'])[:10]
    print(f"  {date}: {row['renewable_pct']:.1f}% ({row['solar']:,.0f} MW solar, {row['wind']:,.0f} MW wind)")

```

--------------------------------

### Get Dataset Updates (cURL)

Source: https://docs.gridstatus.io/developers/api-reference/dataset-updates

This snippet demonstrates how to retrieve dataset updates using cURL. It shows the GET request format, including the endpoint and host. Authentication can be handled via query or header parameters.

```bash
GET /v1/dataset-updates/{dataset_id} HTTP/1.1
Host: api.gridstatus.io
Accept: */*


```

--------------------------------

### Authenticate Grid Status Client with API Key

Source: https://docs.gridstatus.io/developers/getting-started/python-client

Demonstrates two methods for authenticating with the Grid Status API using your API key. The first method uses an environment variable, and the second passes the key directly during client initialization.

```bash
export GRIDSTATUS_API_KEY=your_api_key
```

```python
from gridstatusio import GridStatusClient

client = GridStatusClient(api_key="your_api_key")
```

--------------------------------

### Get Dataset Metadata using JavaScript

Source: https://docs.gridstatus.io/developers/api-reference/dataset-metadata

This JavaScript code snippet shows how to fetch dataset metadata using the `fetch` API. It constructs the URL with the dataset ID and makes a GET request, handling the JSON response.

```javascript
fetch(`https://api.gridstatus.io/v1/datasets/${datasetId}`, {
  method: 'GET',
  headers: {
    'Accept': 'application/json'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error fetching dataset metadata:', error);
  });

```

--------------------------------

### Get Dataset Updates (Python)

Source: https://docs.gridstatus.io/developers/api-reference/dataset-updates

This Python code snippet illustrates how to retrieve dataset updates using the `requests` library. It constructs the API URL with the dataset ID and API key, then sends a GET request. The response is parsed as JSON.

```python
import requests

def get_dataset_updates(dataset_id, api_key):
    url = f"https://api.gridstatus.io/v1/dataset-updates/{dataset_id}"
    params = {
        "api_key": api_key
    }
    try:
        response = requests.get(url, params=params)
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching dataset updates: {e}")
        return None

# Example usage:
# dataset_id = 'your_dataset_id'
# api_key = 'your_api_key'
# updates = get_dataset_updates(dataset_id, api_key)
# if updates:
#     print(updates)
```

--------------------------------

### Get Dataset Updates (JavaScript)

Source: https://docs.gridstatus.io/developers/api-reference/dataset-updates

This JavaScript code snippet shows how to fetch dataset updates from the Grid Status API. It utilizes the `fetch` API to make a GET request to the specified endpoint. Ensure you replace `{dataset_id}` with the actual dataset ID and include your API key.

```javascript
async function getDatasetUpdates(datasetId, apiKey) {
    const url = `https://api.gridstatus.io/v1/dataset-updates/${datasetId}?api_key=${apiKey}`;
    try {
        const response = await fetch(url);
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error fetching dataset updates:', error);
        return null;
    }
}

// Example usage:
// const datasetId = 'your_dataset_id';
// const apiKey = 'your_api_key';
// getDatasetUpdates(datasetId, apiKey).then(data => console.log(data));
```

--------------------------------

### Define ISO Datasets and Fetch Historical Data (Python)

Source: https://docs.gridstatus.io/developers/concepts/recipes

Defines a dictionary of ISO configurations including dataset names, hub locations, and timezones. It then iterates through these configurations to fetch and analyze historical price data for each ISO using the GridStatus.io client. The results include average, maximum, minimum prices, and price volatility.

```python
ISOS = {
    "ERCOT": {
        "load": "ercot_load",
        "lmp": "ercot_lmp_by_settlement_point",
        "hub": "HB_HOUSTON",
        "timezone": "America/Chicago"
    },
    "CAISO": {
        "load": "caiso_load",
        "lmp": "caiso_lmp_real_time_5_min",
        "hub": "TH_SP15_GEN-APND",
        "timezone": "America/Los_Angeles"
    },
    "PJM": {
        "load": "pjm_load",
        "lmp": "pjm_lmp_real_time_5_min",
        "hub": "WESTERN HUB",
        "timezone": "America/New_York"
    }
}

# Fetch yesterday's hourly data for each ISO
results = {}

for iso_name, config in ISOS.items():
    print(f"Fetching {iso_name}...")

    # Get hourly average prices
    prices = client.get_dataset(
        config["lmp"],
        start="2026-01-13",
        end="2026-01-14",
        filter_column="location",
        filter_value=config["hub"],
        resample_frequency="1 hour",
        resample_function="mean",
        timezone=config["timezone"]
    )

    results[iso_name] = {
        "avg_price": prices['lmp'].mean(),
        "max_price": prices['lmp'].max(),
        "min_price": prices['lmp'].min(),
        "price_volatility": prices['lmp'].std()
    }

# Compare results
print("\n=== Multi-ISO Price Comparison (2026-01-13) ===")
print(f"{ 'ISO':<10} {'Avg Price':>12} {'Max':>10} {'Min':>10} {'Volatility':>12}")
print("-" * 58)

for iso_name, stats in results.items():
    print(f"{iso_name:<10} ${stats['avg_price']:>10.2f} ${stats['max_price']:>8.2f} ${stats['min_price']:>8.2f} ${stats['price_volatility']:>10.2f}")
```

--------------------------------

### API Error: Invalid Time Format

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Example of an error response for an invalid time format. The API expects time values in HH:MM:SS format.

```JSON
{
  "status_code": 400,
  "detail": "Invalid time format: 25:00:00. Expected HH:MM:SS"
}
```

--------------------------------

### Filter day-ahead forecasts (Shell, Python)

Source: https://docs.gridstatus.io/developers/concepts/publish-time

Retrieve day-ahead forecasts by using `latest_before` with an offset of -20 hours. This is useful for comparing forecasts published approximately 24 hours in advance.

```shell
curl "https://api.gridstatus.io/v1/datasets/ercot_load_forecast_by_forecast_zone/query?publish_time=latest_before:-20%20hours&start_time=2024-01-01&end_time=2024-01-02&api_key=YOUR_API_KEY"
```

```python
client.get_dataset(
  'ercot_load_forecast_by_forecast_zone',
  publish_time="latest_before:-20 hours",
  start="2024-01-01",
  end="2024-01-02"
)
```
Tokens:
Raw