Eia

Eia#

Module Contents#

Classes Summary#

EIA

Initialize EIA API object

Attributes Summary#

DATASET_CONFIG

Contents#

gridstatus.eia.DATASET_CONFIG[source]#

class gridstatus.eia.EIA(api_key=None)[source]#

Initialize EIA API object

Parameters:: api_key (str, optional) – EIA API key. If not provided, will look for EIA_API_KEY environment variable.

Attributes

BASE_URL

https://api.eia.gov/v2/

Methods

`get_coal_spots`	Retrieve weekly coal commodity spot prices.
`get_daily_spots_and_futures`	Retrieves daily spots and futures for select energy products.
`get_dataset`	Get data from a dataset
`get_grid_monitor`	Retrieves grid monitor data including generation and emissions.
`list_routes`	List all available routes

get_coal_spots(verbose=False)[source]#: Retrieve weekly coal commodity spot prices. TODO: add functionality to grab historicals from https://www.eia.gov/coal/markets/coal_markets_archive_json.php

get_daily_spots_and_futures(verbose=False)[source]#

Retrieves daily spots and futures for select energy products.

Includes Wholesale Spot and Retail Petroleum, Natural Gas. Prompt-Month Futures, broken on EIA side, for Crude, Gasoline, Heating Oil, Natural Gas, Coal, Ethanol.

They are published daily and not persisted, so this should be run once daily.

Returns:: dictionary of DataFrames for each table of values.
Return type:: d

get_dataset(dataset, start, end, facets=None, n_workers=1, verbose=False)[source]#

Get data from a dataset

Only supports “electricity/rto/interchange-data” dataset for now.

Parameters:

dataset (str) – Dataset path
start (str or pd.Timestamp) – Start date
end (str or pd.Timestamp) – End date
facets (dict, optional) – Facets to add to the request header. Defaults to None.
n_workers (int, optional) – Number of workers to use for fetching data. Defaults to 1.
verbose (bool, optional) – Whether to print progress. Defaults to False.

Returns:

Dataframe with data from the dataset

Return type:

pd.DataFrame

get_grid_monitor(area_id=None, area_type=None, n_workers=4, verbose=False)[source]#

Retrieves grid monitor data including generation and emissions.

This function cannot filter by time and fetches all available data. It may be slow if fetching data for all areas.

Parameters:

area_id (str, optional) – ID of area to fetch data for. If provided, fetches data for this area only, ignoring area_type. If both are not provided, fetches data for all areas. Defaults to None.
area_type (str, optional) – Type of areas (‘Region’ or ‘BA’) to fetch data for. Used only if area_id is not provided. If provided, fetches data for all areas of given type. If both are not provided, fetches data for all areas. Defaults to None.
n_workers (int, optional) – Number of workers to use for fetching data. Only used if multiple areas are being fetched. Defaults to 4.
verbose (bool, optional) – If True, prints progress. Defaults to False.

Returns:

Grid monitor data for specified area(s).

Return type:

dict

list_routes(route='/')[source]#: List all available routes