gridstatus

library0.36.0pypypi✓ verified 83d ago

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.

data http-networking

pip install gridstatus

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · GRIDSTATUS

gridstatus

datapythonv0.36.0

Install

17.3s avg

Import

2728ms

Disk

362MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.36.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.628s · 335MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 17.3s · import 1.646s · 324MB

362MB installed

● package 362MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import gridstatus as gs

✗ from gridstatus import *

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

✓ import gridstatus

✗ import grid_status

The correct package name is gridstatus (no underscore).

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())

Debug

Known issues

breakingISO 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.

affects: <0.20.0

deprecatedThe 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.

affects: >=0.30.0

gotchaMany 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).

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'gridstatus'

Library not installed or installed in a different environment.

fix

Run `pip install gridstatus` in your active environment.

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

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').

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

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()`.

Upgrade

Version history

0.36.0latest on PyPI · released Apr 21, 2026

Audit

Dependencies

pandasrequiredData manipulation and output

requestsrequiredHTTP requests to ISO APIs

python-dateutilrequiredDate parsing helpers

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/gridstatus/gridstatus ↗

packagehttps://pypi.org/project/gridstatus/ ↗

homepagehttps://gridstatus.io ↗

changeloghttps://github.com/gridstatus/gridstatus/blob/main/CHANGELOG.md ↗