gridstatusio is a Python client for the GridStatus.io Hosted API, which provides historical and real-time electricity market data from North American ISOs through a single REST API.
Available datasets cover load and demand, fuel and generation mix, forecasts, locational marginal prices (LMPs), interchange, ancillary services, and more. Browse 500+ datasets in the Data Catalog.
The hosted API differs from the open-source gridstatus library in several ways:
| Hosted API | Open-source gridstatus |
|---|---|
| Consistent column names, timestamp formats, and DST handling | Raw data directly from ISO sources |
| Single REST API | Source-specific integrations |
| Historical data queryable immediately | Historical availability depends on each source's retention policy |
| Consistent server-side filtering by time, columns, and row values | Filtering capabilities vary by source |
| Support included with paid subscriptions | Community support |
Use the open-source library when you want raw data directly from the ISOs with no account. We recommend this client when you want normalized, hosted data through a single API.
gridstatusio supports Python 3.10+. Install with uv or pip.
# Standard installation (includes pandas)
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]- Get an API key. Sign up for a Grid Status account and copy your key from the Settings page.
- Provide the key. Set
export GRIDSTATUS_API_KEY=your_api_key, or pass it directly:GridStatusClient(api_key="<your_api_key>"). - Find a dataset. Call
client.list_datasets()or browse the Data Catalog. - Query the dataset. Call
client.get_dataset(...)with the dataset ID and desired time range.
from gridstatusio import GridStatusClient
client = GridStatusClient() # reads GRIDSTATUS_API_KEY from the environment
client.list_datasets()
df = client.get_dataset(
"ercot_fuel_mix",
start="2024-06-01",
end="2024-06-02",
limit=1000,
)Use client.get_dataset_metadata(dataset_id) to get a dataset's description, available time range, columns, and more. It always returns a dictionary, with timestamp fields parsed into timezone-aware datetimes:
metadata = client.get_dataset_metadata("ercot_fuel_mix")
# {
# "id": "ercot_fuel_mix",
# "name": "ERCOT Fuel Mix",
# "earliest_available_time_utc": datetime(2017, 1, 1, 6, 0, tzinfo=timezone.utc),
# "all_columns": [{"name": "interval_start_utc", ...}, ...],
# ...
# }get_dataset(...) supports pandas, polars, or Python objects. Set the return format at the client level or per-call. Dataset metadata is always returned as a dictionary.
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")| 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 |
If return_format is not specified, the client returns pandas DataFrames by default.
# Python format → list of dicts:
# [
# {"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, ...},
# ]Pandas is installed by default, but the library uses lazy loading so it's only imported when needed. In minimal environments, you can install without dependencies and use return_format="python" to avoid pandas entirely:
uv pip install gridstatusio --no-deps
uv pip install requests termcolor tabulatefrom gridstatusio import GridStatusClient
# Must explicitly set return_format="python" to avoid the pandas import
client = GridStatusClient(api_key="your_key", return_format="python")
data = client.get_dataset("ercot_fuel_mix", limit=100)If you don't set return_format="python", the client attempts to use pandas and raises an error if it isn't installed.
usage = client.get_api_usage()Shows the limits for your API key, the start/end of the current usage period, and usage in the current period. A limit of -1 means no limit.
The free plan allows 500,000 rows per month. You can view detailed usage stats in Settings.
The API enforces per-second/minute/hour rate limits. The client retries rate limits (429), server errors (5xx), and network issues with exponential backoff. See the Pricing Page for specific limits.
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)
)Set max_retries=0 to disable retries.
The client checks PyPI for library updates on import. To disable this (e.g. in restricted environments), set:
export GSIO_SKIP_VERSION_CHECK=true- Getting Started
- Finding Hubs and Zones in Pricing Data
- ERCOT Pricing Data
- CAISO April Net Load Analysis
- Stacked Net Load Visualization
- Resample Data to Different Frequencies
For usage or data-access questions, email contact@gridstatus.io.