GridStatus

0.36.0 verified Fri May 01 auth: no python

GridStatus provides a unified Python API to access real-time and historical energy grid data from ISOs (Independent System Operators) across North America, including CAISO, ERCOT, MISO, PJM, NYISO, SPP, ISONE, and AESO. As of v0.36.0, it supports Python 3.10–3.14. The library is actively maintained with frequent releases.

pip install gridstatus

Common errors

error ModuleNotFoundError: No module named 'gridstatus' ↓

cause Library not installed or installed in a different environment.

fix

Run pip install gridstatus in your active environment.

error AttributeError: module 'gridstatus' has no attribute 'CAISO' ↓

cause Trying to access an ISO class on the module level without importing it, or using an outdated version where the class name was different.

fix

Use from gridstatus import CAISO or import gridstatus as gs then gs.CAISO. For older versions (<0.20), use the old name (e.g., 'Caiso').

error ValueError: Invalid date format. Expected 'YYYY-MM-DD' ↓

cause Passing a datetime object or wrongly formatted string as the date parameter.

fix

Convert to string: date='2023-10-01' or use date.today().isoformat().

Warnings

breaking ISO class names changed in v0.20.0: e.g., 'Pjm' became 'PJM'. All ISO names are now uppercase. ↓

fix Update class names to uppercase: CAISO, ERCOT, MISO, PJM, NYISO, SPP, ISONE, AESO.

deprecated The method `get_lmp()` is deprecated in v0.30.0+ in favor of `get_lmp_real_time()` and `get_lmp_day_ahead()`. ↓

fix Replace `get_lmp()` with the appropriate real-time or day-ahead method.

gotcha Many ISO methods require a `date` parameter that must be a string in 'YYYY-MM-DD' format or a datetime.date object, not a datetime.datetime. ↓

fix Pass date as '2023-10-01' or datetime.date(2023,10,1).

Imports

gs
wrong
```
from gridstatus import *
```
correct
```
import gridstatus as gs
```
Star imports are discouraged; use the alias gs for cleaner code.
CAISO
```
from gridstatus import CAISO
```
Direct import of ISO classes is the recommended pattern.
gridstatus
wrong
```
import grid_status
```
correct
```
import gridstatus
```
The correct package name is gridstatus (no underscore).

Quickstart

Quickstart: Initialize an ISO instance (e.g., CAISO) and call a method like get_fuel_mix. No API key required for basic operations.

import gridstatus as gs

# Fetch today's fuel mix from CAISO (no API key needed for most endpoints)
caiso = gs.CAISO()
today_mix = caiso.get_fuel_mix(date='today')
print(today_mix.head())