### Install gridstatusio with notebook dependencies

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/5. Stacked Net Load Visualization.ipynb

Install the gridstatusio package along with necessary notebook dependencies using uv pip.

```bash
uv pip install gridstatusio[notebooks]
```

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

### Install gridstatusio

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Install the library using pip. Optional dependencies can be included for polars or notebook support.

```bash
uv pip install gridstatusio
```

```bash
uv pip install gridstatusio[polars]
```

```bash
uv pip install gridstatusio[notebooks]
```

```bash
uv pip install gridstatusio[all]
```

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

### Install uv and Project Dependencies

Source: https://github.com/gridstatus/gridstatusio/blob/main/developing.md

Installs the uv package manager and then synchronizes development dependencies and installs pre-commit hooks within a virtual environment.

```shell
# Install uv if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment, install dependencies, and install pre-commit hooks
uv sync --dev
pre-commit install
```

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

### Get Dataset in Python Format

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Retrieve data from a dataset in the 'python' format, which returns a list of dictionaries. This example shows fetching the first 5 records.

```python
from gridstatusio import GridStatusClient

client = GridStatusClient(return_format="python")
data = client.get_dataset('ercot_fuel_mix', limit=5)

# Returns a list of dictionaries
# [
#     {"interval_start_utc": "2025-01-01T00:00:00+00:00", "coal": 1234.5, ...},
#     {"interval_start_utc": "2025-01-01T00:05:00+00:00", "coal": 1235.2, ...},
#     ...
# ]
```

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

### Get Data in Pandas Format

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/1. Getting Started.ipynb

Fetches energy data and returns it as a pandas DataFrame. Requires pandas to be installed.

```python
pandas_data = client.get_dataset(
    dataset="ercot_fuel_mix",
    start="2023-04-01",
    end="2023-04-02",
    limit=5,
    return_format="pandas",
    verbose=False,
)
print(f"Type: {type(pandas_data)}")
pandas_data
```

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

### Get Dataset in Polars Format

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Retrieve data from a dataset and receive it as a polars DataFrame. This example fetches 100 records.

```python
from gridstatusio import GridStatusClient

client = GridStatusClient(return_format="polars")
df = client.get_dataset('ercot_fuel_mix', limit=100)

# Returns a polars DataFrame
print(type(df))  # <class 'polars.dataframe.frame.DataFrame'>
```

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

### Get Data in Polars Format

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/1. Getting Started.ipynb

Fetches energy data and returns it as a Polars DataFrame. Requires Polars to be installed.

```python
# Polars format - returns a polars DataFrame
polars_data = client.get_dataset(
    dataset="ercot_fuel_mix",
    start="2023-04-01",
    end="2023-04-02",
    limit=5,
    return_format="polars",
    verbose=False,
)
print(f"Type: {type(polars_data)}")
polars_data
```

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

### Install gridstatusio with Optional Dependencies

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Install the gridstatusio package with optional dependencies for pandas, polars, or notebooks. Use the '[all]' option to include all optional dependencies.

```bash
uv pip install gridstatusio

# With polars support (for polars DataFrames)
uv pip install gridstatusio[polars]

# With notebook support (for running example notebooks)
uv pip install gridstatusio[notebooks]

# With all optional dependencies
uv pip install gridstatusio[all]
```

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

### Import gridstatusio and check version

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/3. ERCOT Pricing Data.ipynb

Import the gridstatusio library and verify its installed version. This is a standard practice to ensure the correct version is being used.

```python
import gridstatusio

gridstatusio.__version__
```

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

### Install gridstatusio Without Dependencies

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Install the gridstatusio package without its default dependencies for advanced users in minimal environments. Manually install required non-pandas dependencies like 'requests' and 'termcolor'.

```bash
# Install without dependencies (advanced usage only)
uv pip install gridstatusio --no-deps

# Then manually install only the required non-pandas dependencies
uv pip install requests termcolor tabulate
```

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

### Initialize GridStatus Client with Python Format

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Initialize the client and explicitly set `return_format='python'` to ensure data is returned as a list of dictionaries, avoiding a dependency on pandas. This is the recommended approach if pandas is not installed.

```python
client = GridStatusClient(api_key="your_key", return_format="python")
data = client.get_dataset('ercot_fuel_mix', limit=100)
```

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

### Get PJM Real-Time 5-Minute LMP Data for Hubs

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

Retrieve real-time 5-minute LMP data for PJM, filtering specifically for locations of type 'HUB'. Ensure the 'gridstatus' library is installed and authenticated.

```python
df_pjm = client.get_dataset(
    dataset="pjm_lmp_real_time_5_min",
    start="2024-04-01 00:00",
    end="2024-04-01 00:05",
    filter_column="location_type",
    filter_value="HUB",
)
df_pjm
```

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

### Get Data in Python List Format

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/1. Getting Started.ipynb

Fetches energy data and returns it as a list of dictionaries. This format has no external dependencies.

```python
# Python format - returns a list of dictionaries (no dependencies required)
python_data = client.get_dataset(
    dataset="ercot_fuel_mix",
    start="2023-04-01",
    end="2023-04-02",
    limit=5,
    return_format="python",
    verbose=False,
)
print(f"Type: {type(python_data)}")
print(f"First row: {python_data[0]}")
```

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

### Import libraries and check gridstatusio version

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/5. Stacked Net Load Visualization.ipynb

Import Plotly graph objects and the gridstatusio library. Check the installed version of gridstatusio.

```python
import plotly.graph_objects as go

import gridstatusio

gridstatusio.__version__
```

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

### Import libraries and check gridstatusio version

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/4. CAISO April Net Load.ipynb

Import pandas for data manipulation and plotly.graph_objects for plotting. Also, import the gridstatusio library and check its installed version.

```python
import pandas as pd
import plotly.graph_objects as go

import gridstatusio

gridstatusio.__version__
```

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

### Get ERCOT Trading Hub Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

Use this snippet to retrieve real-time 15-minute interval data for ERCOT's trading hubs. Ensure the 'gridstatus' library is installed and the client is initialized.

```python
df_ercot_hubs = client.get_dataset(
    dataset="ercot_spp_real_time_15_min",
    start="2024-04-01 00:00",
    end="2024-04-01 00:15",
    filter_column="location_type",
    filter_value="Trading Hub",
)
df_ercot_hubs
```

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

### Plot Time-Series Data with Plotly

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/1. Getting Started.ipynb

Visualize fetched time-series data using Plotly Express. This example plots the 'spp' column against 'interval_start_local', with different locations distinguished by color. Ensure Plotly is installed and the data is in a compatible format (e.g., a Pandas DataFrame).

```python
import plotly.express as px

fig = px.line(
    data_both_apr,
    x="interval_start_local",
    y="spp",
    color="location",
    title="ERCOT SPP in Houston vs West, April 2023",
)
fig.show("png", width=1200, height=800)
```

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

### Fetch CAISO Standardized 5-Min Dataset

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/4. CAISO April Net Load.ipynb

Use this snippet to fetch CAISO standardized 5-minute interval data. Set start and end to None to get all available data. The timezone is set to 'market' for Pacific Time. A QUERY_LIMIT is used to control the maximum number of records returned.

```python
import warnings

warnings.filterwarnings("ignore")

df = client.get_dataset(
    dataset="caiso_standardized_5_min",
    start=None,  # start from beginning of data
    end=None,  # end at most recent data
    timezone="market",  # return time stamps in market time. In this case, Pacific Time
    limit=QUERY_LIMIT,
)
```

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

### Get ISO-NE Internal Hub LMP Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

Retrieve real-time 5-minute preliminary LMP data for ISO-NE's internal hub. Ensure the client is initialized and the dataset name is correct.

```python
df_isone = client.get_dataset(
    dataset="isone_lmp_real_time_5_min_prelim",
    start="2024-04-01 00:00",
    end="2024-04-01 00:05",
    filter_column="location_type",
    filter_value="HUB",
)
df_isone
```

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

### Display DataFrame Info

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/4. CAISO April Net Load.ipynb

Use df.info() to get a concise summary of the DataFrame, including the index dtype and columns, non-null values and their memory usage.

```python
df.info()
```

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

### Fetch ERCOT Real-Time Settlement Point Prices

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/3. ERCOT Pricing Data.ipynb

Retrieves 15-minute real-time settlement point prices for a specified location and date range. Requires the gridstatus library to be installed and authenticated.

```python
df_rt = client.get_dataset(
    dataset="ercot_spp_real_time_15_min",
    start="2024-10-01",
    end="2024-10-02",
    filter_column="location",
    filter_value="HB_HOUSTON",
    timezone="US/Central",
)
df_rt.head(10)
```

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

### Initialize Plotly Figure

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/5. Stacked Net Load Visualization.ipynb

Initializes a Plotly Figure object. This is the starting point for creating any Plotly visualization.

```python
fig = go.Figure()
```

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

### Get API Usage Information

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Retrieve information about your API key's limits, the current usage period, and consumption. A limit of -1 indicates no limit.

```python
usage = client.get_api_usage()
```

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

### Get Real-Time LMPs by Settlement Point

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/3. ERCOT Pricing Data.ipynb

Retrieve real-time LMPs for a specific settlement point within a given date range. Ensure the gridstatus client is initialized and authenticated.

```python
df_rt_lmp = client.get_dataset(
    dataset="ercot_lmp_by_settlement_point",
    start="2024-10-01",
    end="2024-10-02",
    filter_column="location",
    filter_value="BATCAVE_RN",
    timezone="market",
)
df_rt_lmp.head(10)
```

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

### Get ISO-NE Load Zone LMP Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

Retrieve real-time 5-minute preliminary LMP data for ISO-NE's load zones. This may involve retries due to API rate limits.

```python
df_isone_load_zone = client.get_dataset(
    dataset="isone_lmp_real_time_5_min_prelim",
    start="2024-04-01 00:00",
    end="2024-04-01 00:05",
    filter_column="location_type",
    filter_value="LOAD ZONE",
)
df_isone_load_zone
```

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

### Fetch Standardized Hourly Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/5. Stacked Net Load Visualization.ipynb

Fetches standardized hourly data for a specified ISO and time range. Ensure the gridstatus client is initialized and the desired ISO, start date, and end date are set.

```python
ISO = "ercot"
START = "Jul 1, 2023"
END = "Aug 1, 2023"

df = client.get_dataset(
    dataset=f"{ISO}_standardized_hourly",
    start=START,
    end=END,
    timezone="market",
    limit=QUERY_LIMIT,
)

df
```

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

### Resample EIA Interchange Data by Specific Columns

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/6. Resampling Data.ipynb

Use `resample_by` to group EIA interchange data by interval start time, 'to_ba', and 'from_ba' before resampling to daily intervals. This allows for more granular analysis of inter-authority energy flow.

```python
eia_daily_interchange = client.get_dataset(
    dataset="eia_ba_interchange_hourly",
    start="Sep 1, 2023",
    end="Oct 1, 2023",
    resample="1 day",
    resample_by=["interval_start_utc", "to_ba", "from_ba"],
    timezone="market",
    limit=QUERY_LIMIT,
)

eia_daily_interchange
```

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

### Get NYISO Real-Time 5-Minute LMP Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

Retrieve real-time 5-minute LMP data for NYISO zones. This is useful for analyzing zone-level pricing and market dynamics. Ensure you have the gridstatus client initialized.

```python
df_nyiso = client.get_dataset(
    dataset="nyiso_lmp_real_time_5_min",
    start="2024-04-01 00:00",
    end="2024-04-01 00:05",
    filter_column="location_type",
    filter_value="Zone",
)
df_nyiso
```

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

### get_dataset - Alternative return formats

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Specify the desired format for the returned data, such as Polars DataFrames or standard Python lists of dictionaries. This allows flexibility based on installed libraries and downstream processing needs.

```APIDOC
## get_dataset

### Description
Retrieve data from a specified dataset, allowing for different return formats.

### Parameters
#### Query Parameters
- **dataset** (string) - Required - The name of the dataset to retrieve.
- **limit** (integer) - Optional - The maximum number of rows to return.
- **return_format** (string) - Optional - The desired return format ('polars' or 'python'). Defaults to the client's configured format.
- **verbose** (boolean) - Optional - If True, provides verbose output during data retrieval.
```

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

### Initialize GridStatusClient

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/5. Stacked Net Load Visualization.ipynb

Set up the GridStatusClient. The API key can be provided directly or set via the GRIDSTATUS_API_KEY environment variable.

```python
# gridstatusio.GridStatusClient(api_key="YOUR_API_KEY_HERE")
client = gridstatusio.GridStatusClient()
```

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

### GridStatusClient Initialization and Basic Usage

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Demonstrates how to initialize the GridStatusClient and fetch data for a specific dataset, including setting limits and date ranges.

```APIDOC
## GridStatusClient Initialization and Basic Usage

### Description
Initialize the GridStatusClient and fetch data for a specific dataset. You can specify limits and date ranges for your queries.

### Method
`GridStatusClient.get_dataset(dataset_id: str, limit: int = None, start: str = None, end: str = None, return_format: str = None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **dataset_id** (str) - Required - The identifier for the dataset to retrieve.
- **limit** (int) - Optional - The maximum number of records to return.
- **start** (str) - Optional - The start date for the data query (YYYY-MM-DD).
- **end** (str) - Optional - The end date for the data query (YYYY-MM-DD).
- **return_format** (str) - Optional - The desired format for the returned data ('pandas', 'polars', or 'python'). Defaults to 'pandas'.

### Request Example
```python
from gridstatusio import GridStatusClient

client = GridStatusClient()
data = client.get_dataset('ercot_fuel_mix', limit=100, start='2025-01-01', end='2025-01-02')
```

### Response
#### Success Response (200)
Returns data in the specified format (pandas DataFrame, polars DataFrame, or list of dictionaries).

#### Response Example (Python Format)
```json
[
    {"interval_start_utc": "2025-01-01T00:00:00+00:00", "coal": 1234.5, ...},
    {"interval_start_utc": "2025-01-01T00:05:00+00:00", "coal": 1235.2, ...},
    ...
]
```
```

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

### Initialize GridStatusClient

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/3. ERCOT Pricing Data.ipynb

Set up the GridStatusClient for API interaction. The API key can be provided via an environment variable or directly in the constructor.

```python
client = gridstatusio.GridStatusClient()
client
```

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

### GridStatusClient.__init__

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Instantiates the client with an API key and optional configuration for return format, retry behavior, and transport settings. If api_key is omitted, the GRIDSTATUS_API_KEY environment variable is used.

```APIDOC
## GridStatusClient.__init__ 

### Description
Instantiates the client with an API key and optional configuration for return format, retry behavior, and transport settings. If `api_key` is omitted, the `GRIDSTATUS_API_KEY` environment variable is used. The default `return_format` is `"pandas"` when pandas is installed, otherwise `"python"`.

### Method
```python
GridStatusClient(
    api_key: Optional[str] = None,
    return_format: Literal["pandas", "polars", "python"] = "pandas",
    max_retries: int = 5,
    base_delay: float = 2.0,
    exponential_base: float = 2.0,
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import os
from gridstatusio import GridStatusClient

# From environment variable (recommended)
client = GridStatusClient()

# Explicit API key and custom retry / format settings
client = GridStatusClient(
    api_key=os.environ["GRIDSTATUS_API_KEY"],
    return_format="pandas",   # "pandas" | "polars" | "python"
    max_retries=5,            # retry on 429, 5xx, network errors (default: 5)
    base_delay=2.0,           # base seconds for exponential backoff (default: 2.0)
    exponential_base=2.0,     # backoff multiplier: delay = base_delay * (exponential_base ** retry)
)

print(client)
# GridStatusClient(host=https://api.gridstatus.io/v1)
```

### Response
#### Success Response (200)
Returns an instance of `GridStatusClient`.

#### Response Example
```
GridStatusClient(host=https://api.gridstatus.io/v1)
```
```

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

### Import GridStatusClient

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/1. Getting Started.ipynb

Import the main client class from the gridstatusio library.

```python
from gridstatusio import GridStatusClient
```

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

### Create GridStatusClient Instance

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Instantiate the client with an API key. The API key can be provided directly or read from the GRIDSTATUS_API_KEY environment variable. Custom settings for return format, retries, and base delay can also be configured.

```python
import os
from gridstatusio import GridStatusClient

# From environment variable (recommended)
client = GridStatusClient()

# Explicit API key and custom retry / format settings
client = GridStatusClient(
    api_key=os.environ["GRIDSTATUS_API_KEY"],
    return_format="pandas",   # "pandas" | "polars" | "python"
    max_retries=5,            # retry on 429, 5xx, network errors (default: 5)
    base_delay=2.0,           # base seconds for exponential backoff (default: 2.0)
    exponential_base=2.0,     # backoff multiplier: delay = base_delay * (exponential_base ** retry)
)

print(client)
# GridStatusClient(host=https://api.gridstatus.io/v1)
```

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

### Initialize GridStatusClient and Query Dataset

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Initialize the GridStatusClient and query a dataset. Ensure your API key is set as an environment variable or passed during client initialization. Use the 'limit' parameter to control the number of rows returned.

```python
from gridstatusio import GridStatusClient
client = GridStatusClient()

data = client.get_dataset('ercot_fuel_mix', limit=100, start='2025-01-01', end='2025-01-02')
```

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

### Filter by Publish Time with get_dataset

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Control which report revisions are returned for forecast datasets using `publish_time`. 'latest_report' gets all rows from the most recent report, while 'latest' gets the most recent value for each interval.

```python
from gridstatusio import GridStatusClient

client = GridStatusClient()

# latest_report: all rows from the single most-recently published report
df_latest_report = client.get_dataset(
    dataset="miso_wind_forecast_hourly",
    publish_time="latest_report",
    verbose=False,
)
assert df_latest_report["publish_time_utc"].nunique() == 1
```

```python
# latest: for each interval timestamp, return only the most recently published value
df_latest = client.get_dataset(
    dataset="miso_wind_forecast_hourly",
    publish_time="latest",
    start="2025-01-01",
    end="2025-01-03",
    verbose=False,
)
```

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

### Initialize GridStatusClient

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

Initialize the GridStatusClient to interact with the gridstatus.io API. This client will be used for all subsequent data retrieval operations.

```python
from gridstatusio import GridStatusClient

client = GridStatusClient()
```

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

### get_dataset - Pagination and performance options

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Control how data is fetched in chunks using pagination. Options include cursor-based (default, faster) and offset-based pagination, along with settings for page size and delays between requests.

```APIDOC
## get_dataset

### Description
Retrieve data from a specified dataset with advanced pagination and performance controls.

### Parameters
#### Query Parameters
- **dataset** (string) - Required - The name of the dataset to retrieve.
- **start** (string) - Required - The start date for the data retrieval (YYYY-MM-DD).
- **end** (string) - Required - The end date for the data retrieval (YYYY-MM-DD).
- **limit** (integer) - Optional - The maximum number of rows to return.
- **page_size** (integer) - Optional - The number of rows to fetch per HTTP request.
- **use_cursor_pagination** (boolean) - Optional - Whether to use cursor-based pagination (default: True).
- **sleep_time** (float) - Optional - Seconds to sleep between fetching pages (default: 0).
- **verbose** (boolean) - Optional - If True, provides verbose output during data retrieval.
```

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

### Fetch Daily Peak Report

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Retrieve a pre-built daily peak report for a specified ISO and date. Requires a paid GridStatus plan. Accepts string or datetime objects for `market_date`.

```python
from datetime import datetime
from gridstatusio import GridStatusClient

client = GridStatusClient()

# Today's report for ERCOT
report = client.get_daily_peak_report(iso="ERCOT")
print(report["ISO"])
print(report["market_date"])

# Historical report for CAISO on a specific date
report_caiso = client.get_daily_peak_report(
    iso="CAISO",
    market_date="2024-07-01",   # string "YYYY-MM-DD" or datetime object
)
# {"ISO": "CAISO", "market_date": "2024-07-01", "peak_load_mw": ..., "peak_lmp": ...}

# Using a datetime object
report_spp = client.get_daily_peak_report(
    iso="SPP",
    market_date=datetime(2024, 7, 10),
)
assert report_spp["market_date"] == "2024-07-10"
```

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

### get_dataset - Filtering by publish time

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Retrieve a dataset filtered by the time window when the data was published. This is useful for ensuring you are getting the most up-to-date or specific historical versions of a dataset.

```APIDOC
## get_dataset

### Description
Retrieve data from a specified dataset, with options for filtering by publication time.

### Parameters
#### Query Parameters
- **dataset** (string) - Required - The name of the dataset to retrieve.
- **start** (string) - Required - The start date for the data retrieval (YYYY-MM-DD).
- **end** (string) - Required - The end date for the data retrieval (YYYY-MM-DD).
- **publish_time_start** (string) - Optional - Inclusive start timestamp for filtering by publication time (ISO 8601 format).
- **publish_time_end** (string) - Optional - Exclusive end timestamp for filtering by publication time (ISO 8601 format).
- **verbose** (boolean) - Optional - If True, provides verbose output during data retrieval.
```

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

### Filter Data by Location

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/1. Getting Started.ipynb

Use the `filter_column` and `filter_value` parameters to retrieve data for a specific location. This example fetches day-ahead prices for the Houston Hub in April 2023.

```python
data_houston_apr = client.get_dataset(
    dataset="ercot_spp_day_ahead_hourly",
    start="2023-04-01",
    end="2023-05-01",
    filter_column="location",
    filter_value="HB_HOUSTON",
    timezone="market",
    limit=QUERY_LIMIT,
)

data_houston_apr
```

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

### Run Tests and Linting

Source: https://github.com/gridstatus/gridstatusio/blob/main/developing.md

Commands to execute all tests, lint the code, and automatically fix linting errors. These should be run before submitting a pull request.

```shell
# Run all tests
make test
# Lint the code
make lint
# Fix linting errors
make lint-fix
```

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

### Fetch ERCOT SPP Day-Ahead Hourly Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/3. ERCOT Pricing Data.ipynb

Query for a specific interval of ERCOT SPP day-ahead hourly data. Requires specifying the dataset, start and end times, and timezone.

```python
interval_data = client.get_dataset(
    dataset="ercot_spp_day_ahead_hourly",
    start="2024-10-01 00:00:00",
    end="2024-10-01 01:00:00",
    timezone="US/Central",
)

locations = interval_data[["location", "location_type"]].drop_duplicates()
locations
```

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

### Fetch Dataset with Publish Time Window

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Retrieve data within a specific publish time window. The `publish_time_start` is inclusive and `publish_time_end` is exclusive.

```python
df_window = client.get_dataset(
    dataset="ercot_load_forecast_by_forecast_zone",
    start="2023-10-01",
    end="2023-10-02",
    publish_time_start="2023-09-30T12:00:00Z",   # inclusive
    publish_time_end="2023-10-01T12:00:00Z",     # exclusive
    verbose=False,
)
```

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

### Add Load Trace

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/5. Stacked Net Load Visualization.ipynb

Adds a 'Load' trace to display the actual electricity load. This trace is rendered as lines with a specified red color and width.

```python
fig.add_trace(
    go.Scatter(
        x=df["interval_start_local"],
        y=df["load.load"],
        name="Load",
        mode="lines",
        line=dict(color=red, width=5),
    )
)
```

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

### List Available Datasets

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Retrieves a list of all available datasets that can be queried from the GridStatus.io API.

```APIDOC
## List Available Datasets

### Description
Retrieves a list of all available datasets that can be queried from the GridStatus.io API.

### Method
`GridStatusClient.list_datasets()`

### Parameters
None

### Request Example
```python
from gridstatusio import GridStatusClient

client = GridStatusClient()
datasets = client.list_datasets()
```

### Response
#### Success Response (200)
Returns a list of dataset identifiers.

#### Response Example
```json
["dataset_id_1", "dataset_id_2", ...]
```
```

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

### Fetch CAISO Standardized 5-Minute Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/4. CAISO April Net Load.ipynb

Import necessary libraries and use the GridStatusClient to fetch 'caiso_standardized_5_min' dataset. Data is retrieved from the beginning to the most recent entry, with timestamps returned in market time (Pacific Time).

```python
import warnings

warnings.filterwarnings("ignore")

df = client.get_dataset(
    dataset="caiso_standardized_5_min",
    start=None,  # start from beginning of data
    end=None,  # end at most recent data
    timezone="market",  # return time stamps in market time. In this case, Pacific Time
)
```

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

### Configure GridStatusClient with Aggressive Retries

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Use this configuration for high-volume workloads requiring robust error handling. The delay schedule is explicitly commented for clarity.

```python
client = GridStatusClient(
    max_retries=8,
    base_delay=1.0,
    exponential_base=1.5,
    # delay schedule: 1s, 1.5s, 2.25s, 3.4s, 5.1s, 7.6s, 11.4s, 17.1s
)
```

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

### Set Default Return Format for GridStatusClient

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Set the default data return format when initializing the GridStatusClient. Supported formats are 'pandas', 'polars', and 'python'.

```python
from gridstatusio import GridStatusClient

# Set default format when creating the client
client = GridStatusClient(return_format="pandas")  # or "polars" or "python"

# Override format for a specific call
data = client.get_dataset('ercot_fuel_mix', limit=100, return_format="python")
```

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

### Get ERCOT Load Zone Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

This snippet retrieves real-time 15-minute interval data for ERCOT's load zones. It's useful for analyzing regional demand. Rate limiting may occur, so consider implementing retries.

```python
df_ercot_zones = client.get_dataset(
    dataset="ercot_spp_real_time_15_min",
    start="2024-04-01 00:00",
    end="2024-04-01 00:15",
    filter_column="location_type",
    filter_value="Load Zone",
)
df_ercot_zones
```

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

### Paginate Dataset with Cursor or Offset

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Control pagination using `page_size` and `use_cursor_pagination`. Cursor pagination is generally faster for large datasets. `sleep_time` can be set to avoid rate limits.

```python
from gridstatusio import GridStatusClient

client = GridStatusClient()

# Cursor pagination (default) — fastest for large fetches
df = client.get_dataset(
    dataset="ercot_lmp_by_bus",
    start="2023-01-01",
    end="2023-01-02",
    limit=500,
    page_size=100,              # rows per HTTP request
    use_cursor_pagination=True, # default
    sleep_time=0,               # seconds between pages (0 = no delay)
    verbose=True,
)

# Offset pagination — useful when debugging or comparing results
df_offset = client.get_dataset(
    dataset="ercot_lmp_by_bus",
    start="2023-01-01",
    end="2023-01-02",
    limit=500,
    page_size=100,
    use_cursor_pagination=False,
    verbose=False,
)
```

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

### Fetch ERCOT Ancillary Services Prices

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/3. ERCOT Pricing Data.ipynb

Use this snippet to retrieve ancillary services prices for ERCOT. Specify the dataset, start and end dates, and timezone. The `.head(10)` method displays the first 10 rows of the resulting DataFrame.

```python
df_rt_lmp = client.get_dataset(
    dataset="ercot_as_prices",
    start="2024-10-01",
    end="2024-10-02",
    timezone="market",
)
df_rt_lmp.head(10)
```

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

### GridStatusClient.list_datasets

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Browse available datasets. Prints a formatted table of every dataset available to the authenticated API key and optionally returns the list. Accepts a case-insensitive `filter_term` matched against dataset ID, name, and description.

```APIDOC
## GridStatusClient.list_datasets 

### Description
Browse available datasets. Prints a formatted table of every dataset available to the authenticated API key and optionally returns the list. Accepts a case-insensitive `filter_term` matched against dataset ID, name, and description.

### Method
```python
list_datasets(
    filter_term: Optional[str] = None,
    return_list: bool = False,
    verbose: bool = True,
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from gridstatusio import GridStatusClient

client = GridStatusClient()

# Print all datasets (colorised table output)
client.list_datasets()

# Filter and return as a list for programmatic use
fuel_mix_datasets = client.list_datasets(filter_term="fuel_mix", return_list=True)
# [
#   {"id": "ercot_fuel_mix", "name": "ERCOT Fuel Mix", "description": "...",
#    "earliest_available_time_utc": "2011-01-01T00:00:00+00:00",
#    "latest_available_time_utc": "2025-12-03T23:55:00+00:00", ...},
#   {"id": "caiso_fuel_mix", ...},
#   ...
# ]
print(f"Found {len(fuel_mix_datasets)} fuel-mix datasets")

# Search by ISO
lmp_datasets = client.list_datasets(filter_term="lmp", return_list=True)
print([d["id"] for d in lmp_datasets])
# ['ercot_spp_day_ahead_hourly', 'caiso_lmp_day_ahead_hourly', 'pjm_lmp_...', ...]
```

### Response
#### Success Response (200)
If `return_list` is `True`, returns a list of dictionaries, where each dictionary represents a dataset. Otherwise, prints a formatted table to the console.

#### Response Example
```json
[
  {
    "id": "ercot_fuel_mix",
    "name": "ERCOT Fuel Mix",
    "description": "ERCOT fuel mix data.",
    "earliest_available_time_utc": "2011-01-01T00:00:00+00:00",
    "latest_available_time_utc": "2025-12-03T23:55:00+00:00",
    "interval_minutes": 5,
    "data_types": ["coal", "natural_gas", "nuclear", "solar", "wind", "hydro", "other"]
  }
]
```
```

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

### Configuring Return Format

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Specifies how to configure the return format for data fetched from the API, supporting pandas, polars, and Python objects.

```APIDOC
## Configuring Return Format

### Description
The client supports three return formats for data: pandas DataFrames, polars DataFrames, and Python objects (list of dictionaries). You can specify the format at the client level or per-call.

### Client Initialization
Set the default format when creating the client:
```python
from gridstatusio import GridStatusClient

# Set default format to pandas (default)
client_pandas = GridStatusClient(return_format="pandas")

# Set default format to polars
client_polars = GridStatusClient(return_format="polars")

# Set default format to python
client_python = GridStatusClient(return_format="python")
```

### Per-Call Override
Override the default format for a specific call:
```python
from gridstatusio import GridStatusClient

client = GridStatusClient() # Default is pandas
data = client.get_dataset('ercot_fuel_mix', limit=100, return_format="python")
```

### Format Options
| Format | Return Type | Description |
|--------|------------|-------------|
| `"pandas"` | `pd.DataFrame` | Pandas DataFrame with parsed datetime columns |
| `"polars"` | `pl.DataFrame` | Polars DataFrame with parsed datetime columns |
| `"python"` | `list[dict]` | List of dictionaries with parsed datetime columns |
```

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

### Query MISO Hubs and Filter by Location Name

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

Retrieve real-time 5-minute pricing data for MISO, initially filtering by 'location_type' as 'Hub'. Subsequently, further filter the results to include only locations containing 'HUB' in their names to identify state-level hubs.

```python
df_miso = client.get_dataset(
    dataset="miso_lmp_real_time_5_min",
    start="2024-04-01 00:00",
    end="2024-04-01 00:05",
    filter_column="location_type",
    filter_value="Hub",
)

df_miso_hubs = df_miso[df_miso["location"].str.contains("HUB")]
df_miso_hubs
```

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

### Visualize Telemetered Net Output with Plotly

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/1. Getting Started.ipynb

Generates a bar chart showing telemetered net output over time, colored by resource name. Requires Plotly and pandas DataFrames.

```python
fig = px.bar(
    big_star,
    x="interval_start_local",
    y="telemetered_net_output",
    color="resource_name",
    title="BIG_STAR_UNIT1 and BIG_STAR_UNIT2 Output",
)

fig.show("svg", width=1200, height=800)
```

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

### Server-Side Resampling with get_dataset

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Resample data on the server before transfer by specifying a frequency string (e.g., '1 hour') and an aggregation function (e.g., 'mean'). Use `resample_by` to group by additional columns.

```python
from gridstatusio import GridStatusClient

client = GridStatusClient()

# Hourly mean for one day → exactly 24 rows
df_hourly = client.get_dataset(
    dataset="isone_fuel_mix",
    start="2023-01-01",
    end="2023-01-02",
    resample="1 hour",
    resample_function="mean",   # default
    verbose=False,
)
assert len(df_hourly) == 24
```

```python
# Daily max load for two days → 2 rows
df_daily_max = client.get_dataset(
    dataset="caiso_load",
    start="2023-09-01",
    end="2023-09-03",
    resample="1 day",
    resample_function="max",
    verbose=False,
)
assert len(df_daily_max) == 2
```

```python
# Resample interchange grouped by BA pair
df_ba = client.get_dataset(
    dataset="eia_ba_interchange_hourly",
    start="2023-09-01",
    end="2023-09-03",
    resample="1 day",
    resample_by=["interval_start_utc", "to_ba", "from_ba"],
    verbose=False,
)
print(df_ba.columns.tolist())
# ['interval_start_utc', 'interval_end_utc', 'to_ba', 'from_ba', 'mw']
```

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

### Select Specific Columns with get_dataset

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Fetch only specified columns along with the time-index column to reduce data transfer. Ensure the desired columns are listed in the `columns` parameter.

```python
from gridstatusio import GridStatusClient

client = GridStatusClient()

df = client.get_dataset(
    dataset="ercot_sced_gen_resource_60_day",
    columns=["sced_timestamp_utc", "resource_name"],
    limit=100,
    verbose=False,
)
# Only two columns returned
print(df.columns.tolist())
# ['sced_timestamp_utc', 'resource_name']
```

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

### Display CAISO Net Load DataFrame

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/4. CAISO April Net Load.ipynb

This code displays the first few rows of the 'df' DataFrame, which contains CAISO net load data. It's useful for a quick inspection of the data's format and content.

```python
df
```

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

### Fetch Raw 5-Minute Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/6. Resampling Data.ipynb

Query the API for raw 5-minute interval data for a specified dataset and date range. Ensure a limit is set to control the number of returned rows.

```python
df_5min = client.get_dataset(
    dataset="caiso_load",
    start="Sep 1, 2023",
    end="Sep 2, 2023",
    timezone="market",
    limit=QUERY_LIMIT,
)

df_5min
```

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

### GridStatusClient.get_daily_peak_report

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Fetches a pre-compiled daily peak report for a specified ISO (Independent System Operator) and market date. This report includes key metrics like peak load and peak LMP.

```APIDOC
## GridStatusClient.get_daily_peak_report

### Description
Fetches a pre-built daily peak report for a given ISO and date.

### Parameters
#### Query Parameters
- **iso** (string) - Required - The ISO for which to retrieve the report (e.g., 'ERCOT', 'CAISO').
- **market_date** (string or datetime) - Optional - The specific market date for the report in 'YYYY-MM-DD' format or as a datetime object. Defaults to the current date if not provided.
```

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

### Inspect DataFrame Head and Tail

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/4. CAISO April Net Load.ipynb

After fetching data, use df.head() to view the first few rows and df.tail() to view the last few rows of the DataFrame.

```python
df.head()
```

```python
df.tail()
```

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

### Add Solar Fuel Mix Trace

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/5. Stacked Net Load Visualization.ipynb

Adds a 'Solar' trace for the solar fuel mix. Similar to the wind trace, it fills to the next y-axis and belongs to the 'one' stack group, using a yellow fill color.

```python
fig.add_trace(
    go.Scatter(
        x=df["interval_start_local"],
        y=df["fuel_mix.solar"],
        name="Solar",
        fill="tonexty",
        stackgroup="one",
        mode="none",
        fillcolor=yellow,
    )
)
```

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

### Fetch Resampled Data with Min and Max Functions

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/6. Resampling Data.ipynb

Use the `resample_function` parameter to specify aggregation methods like 'min' or 'max' when fetching data. This is useful for understanding the range of values within resampling windows.

```python
df_hourly_min = client.get_dataset(
    dataset="caiso_load",
    start="Sep 1, 2023",
    end="Sep 2, 2023",
    resample="1 hour",
    resample_function="min",
    timezone="market",
    limit=QUERY_LIMIT,
)

df_hourly_max = client.get_dataset(
    dataset="caiso_load",
    start="Sep 1, 2023",
    end="Sep 2, 2023",
    resample="1 hour",
    resample_function="max",
    timezone="market",
    limit=QUERY_LIMIT,
)

df_hourly_min.head(10)
```

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

### Configure GridStatusClient with No Retries

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Disable retries by setting max_retries to 0. This is useful for interactive sessions or debugging purposes.

```python
client_no_retry = GridStatusClient(max_retries=0)
```

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

### Check API Usage and Limits

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Query your current API plan limits, usage period, and consumed request/row counts. A limit of -1 indicates unlimited.

```python
from gridstatusio import GridStatusClient

client = GridStatusClient()

usage = client.get_api_usage()
# {
#   "plan_name": "Free",
#   "rows_per_response": 10000,
#   "total_requests_limit": 1000,
#   "total_rows_limit": 1000000,
#   "rate_limit_per_second": 2,
#   "rate_limit_per_minute": 60,
#   "rate_limit_per_hour": 1000,
#   "current_period_start": "2025-12-01T00:00:00+00:00",
#   "current_period_end": "2026-01-01T00:00:00+00:00",
#   "current_period_usage": {
#       "total_requests": 42,
#       "total_rows_returned": 85000
#   }
# }

rows_used = usage["current_period_usage"]["total_rows_returned"]
rows_limit = usage["total_rows_limit"]
if rows_limit != -1:
    print(f"Used {rows_used:,} / {rows_limit:,} rows ({rows_used/rows_limit:.1%})")
```

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

### Configure Client with Custom Retry Settings

Source: https://github.com/gridstatus/gridstatusio/blob/main/README.md

Customize the retry behavior for failed requests due to rate limits, server errors, or network issues. Adjust `max_retries`, `base_delay`, and `exponential_base` to control the retry attempts and delays. Set `max_retries=0` to disable retries.

```python
client = GridStatusClient(
    max_retries=3,        # Maximum retries (default: 5)
    base_delay=1.0,       # Base delay in seconds (default: 2.0)
    exponential_base=1.5  # Exponential backoff multiplier (default: 2.0)
)
```

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

### GridStatusClient.get_api_usage

Source: https://context7.com/gridstatus/gridstatusio/llms.txt

Retrieves information about your current API plan, including usage limits, the current billing period, and the amount of data consumed so far within that period.

```APIDOC
## GridStatusClient.get_api_usage

### Description
Check API usage and limits for the current account.

### Returns
- **dict** - An object containing API usage details, including plan name, limits, current period, and usage counts.
```

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

### Fetch CAISO Trading Hubs LMP Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/2. ISO Hubs.ipynb

Retrieve real-time 5-minute LMP data for CAISO trading hubs. Ensure the 'location_type' filter is set to 'Trading Hub'.

```python
df_caiso = client.get_dataset(
    dataset="caiso_lmp_real_time_5_min",
    start="2024-04-01 00:00",
    end="2024-04-01 00:05",
    filter_column="location_type",
    filter_value="Trading Hub",
)
df_caiso
```

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

### Fetch Hourly Resampled CAISO Load Data

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/6. Resampling Data.ipynb

Fetches CAISO load data and resamples it to hourly intervals. Specify the dataset, date range, resampling frequency, and timezone. The `limit` parameter controls the maximum number of rows returned.

```python
df_hourly = client.get_dataset(
    dataset="caiso_load",
    start="Sep 1, 2023",
    end="Sep 2, 2023",
    resample="1 hour",
    timezone="market",
    limit=QUERY_LIMIT,
)
df_hourly.head(10)
```

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

### Fetch Specific Columns for Resampling

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/6. Resampling Data.ipynb

Fetch only the 'prc' column from the 'ercot_real_time_as_monitor' dataset for a specific date range. This prepares the data for subsequent resampling.

```python
prc_df_raw = client.get_dataset(
    dataset="ercot_real_time_as_monitor",
    start="Sep 1, 2023",
    end="Sep 2, 2023",
    columns=["prc"],
    timezone="market",
    limit=QUERY_LIMIT,
)

prc_df_raw
```

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

### Add Wind Fuel Mix Trace

Source: https://github.com/gridstatus/gridstatusio/blob/main/Examples/5. Stacked Net Load Visualization.ipynb

Adds a 'Wind' trace representing the wind fuel mix. It's set to fill to the next y-axis ('tonexty') and is part of the 'one' stack group, using a light blue fill color.

```python
fig.add_trace(
    go.Scatter(
        x=df["interval_start_local"],
        y=df["fuel_mix.wind"],
        name="Wind",
        fill="tonexty",
        stackgroup="one",
        mode="none",
        fillcolor=light_blue,
    )
)
```