Eia

Eia#

Module Contents#

Classes Summary#

EIA

Initialize EIA API object

Attributes Summary#

DATASET_CONFIG

HENRY_HUB_NATURAL_GAS_SPOT_PRICES_PATH

HENRY_HUB_TIMEZONE

logger

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

api_key

None

BASE_URL

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

default_timezone

‘US/Central’

session

None

Methods

get_coal_spots([verbose])

Retrieve weekly coal commodity spot prices.

get_daily_spots_and_futures([verbose])

Retrieves daily spots and futures for select energy products.

get_dataset(dataset, start, end[, frequency, facets, ...])

Get data from a dataset

get_generators(→ Dict[str, pandas.DataFrame])

get_grid_monitor([area_id, area_type, n_workers, verbose])

Retrieves grid monitor data including generation and emissions.

get_henry_hub_natural_gas_spot_prices(date[, end, verbose])

Retrieve Henry Hub natural gas spot prices.

list_facets([route])

List all available facets and facet options for a dataset.

list_routes([route])

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, frequency='hourly', facets=None, n_workers=1, verbose=False)[source]#

Get data from a dataset

Currently supports the following datasets:

  • “electricity/rto/interchange-data”

  • “electricity/rto/region-data”

  • “electricity/rto/region-sub-ba-data”

  • “electricity/rto/fuel-type-data”

Parameters:

  • dataset (str) – Dataset path

  • start (str or pd.Timestamp) – Start date

  • end (str or pd.Timestamp) – End date

  • frequency (str) – Specifies the data frequency. Accepts [hourly, local-hourly]. Where hourly is refers to the UTC time and local-hourly is the local time.

  • hourly. (Default is)

  • 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_generators(date: str | datetime.datetime, end: str | datetime.datetime = None, verbose: bool = False) → Dict[str, pandas.DataFrame][source]#
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

get_henry_hub_natural_gas_spot_prices(date, end=None, verbose=False)[source]#

Retrieve Henry Hub natural gas spot prices.

https://www.eia.gov/dnav/ng/hist/rngwhhdD.htm

Parameters:

  • date (str or pd.Timestamp) – Date to fetch data for.

  • end (str or pd.Timestamp) – End date to fetch data for.

Returns:

DataFrame with Henry Hub natural gas spot prices.

Return type:

pd.DataFrame

list_facets(route='/')[source]#

List all available facets and facet options for a dataset.

list_routes(route='/')[source]#

List all available routes

gridstatus.eia.HENRY_HUB_NATURAL_GAS_SPOT_PRICES_PATH = 'natural-gas/pri/fut'[source]#
gridstatus.eia.HENRY_HUB_TIMEZONE = 'US/Central'[source]#
gridstatus.eia.logger[source]#
Contents