energy_data_retrieval.sources.eia.client#

Bounded EIA API v2 and public EIA-930 generation retrieval.

EIA-930 hourly labels denote the end of an hour. API frequency=hourly uses UTC; local-hourly is deliberately not requested. Energy is retained in MWh, with a separate interval start. Monthly plant data keep their reporting month and every fuel/prime-mover dimension; month labels are not SCADA samples.

class energy_data_retrieval.sources.eia.client.EIAResult(frame, requests)[source]#

Bases: object

Normalized observations and sanitized request provenance for all pages.

Parameters:
frame: DataFrame#
requests: tuple[RequestRecord, ...]#
energy_data_retrieval.sources.eia.client.normalize_hourly_generation(rows)[source]#

Normalize API fuel-type rows with UTC hour-ending labels and MWh units.

Original API fields are retained, except value becomes numeric and its untouched representation is retained as source_value. Exact duplicate keys collapse; conflicting values fail. No missing hours are filled.

Parameters:

rows (Sequence[JSONValue])

Return type:

DataFrame

energy_data_retrieval.sources.eia.client.normalize_monthly_generation(rows)[source]#

Normalize plant/fuel/prime-mover monthly net generation without aggregation.

timestamp is a UTC month label for indexing, not an assertion about the plant’s reporting timezone. reporting_month retains the source label. Aggregated ALL categories remain explicitly visible and must not be summed with their detail rows. These records are not individual generators.

Parameters:

rows (Sequence[JSONValue])

Return type:

DataFrame

energy_data_retrieval.sources.eia.client.balance_file_url(year, half)[source]#

Official public six-month EIA-930 balance file URL (no API key).

Parameters:
  • year (int)

  • half (int)

Return type:

str

energy_data_retrieval.sources.eia.client.parse_balance_csv(text, *, respondents=None, fuel_types=None, maximum_rows=500000)[source]#

Parse reported fuel generation from a public EIA-930 six-month balance CSV.

Uses native UTC Time at End of Hour and only unadjusted fuel columns. Source headers label hourly average power as MW. Multiplication by the explicit one-hour interval gives MWh; source_unit retains MW. Imputed, adjusted, demand, interchange and total-generation columns are not mixed into the fuel series. Missing fuels are not inferred as zero.

Parameters:
  • text (str)

  • respondents (Sequence[str] | None)

  • fuel_types (Sequence[str] | None)

  • maximum_rows (int)

Return type:

DataFrame

class energy_data_retrieval.sources.eia.client.EIAClient(http, api_key='', page_size=5000, maximum_pages=200)[source]#

Bases: object

EIA source client; API credentials are never included in repr or provenance.

Parameters:
  • http (HTTPClient)

  • api_key (str)

  • page_size (int)

  • maximum_pages (int)

http: HTTPClient#
api_key: str#
page_size: int#
maximum_pages: int#
classmethod from_environment(http)[source]#

Use a free user-registered EIA_API_KEY for API requests.

Parameters:

http (HTTPClient)

Return type:

EIAClient

metadata(dataset)[source]#

Retrieve official route metadata (frequencies, facets, and data fields).

Parameters:

dataset (Literal['hourly', 'monthly'])

Return type:

tuple[dict[str, JSONValue], RequestRecord]

hourly_generation(start, end, *, respondents, fuel_types=None)[source]#

Hourly net generation by fuel, inclusive UTC hour-ending label bounds.

Select BAs (e.g. CISO), regions or US48 explicitly. These levels overlap and must not be summed together. Full advertised pagination is fetched or an error is raised; an empty successful result is valid.

Parameters:
  • start (datetime)

  • end (datetime)

  • respondents (Sequence[str])

  • fuel_types (Sequence[str] | None)

Return type:

EIAResult

monthly_generation(start, end, *, plant_codes, fuel_types=None, prime_movers=None)[source]#

EIA-923 plant monthly net generation, inclusive YYYY-MM bounds.

Preserve plantCode, fuel2002, fuelType and primeMover, including any provider aggregate rows. Filter one consistent aggregation level before summing; a plant with multiple fuels/prime movers has several records.

Parameters:
  • start (str)

  • end (str)

  • plant_codes (Sequence[str])

  • fuel_types (Sequence[str] | None)

  • prime_movers (Sequence[str] | None)

Return type:

EIAResult

balance_file(year, half, path, *, respondents=None, fuel_types=None)[source]#

Download and parse a key-free six-month reported-generation CSV.

The native file and its verified request manifest remain at path. Files may be tens of MB; the shared HTTP byte cap still applies. Use narrow respondent/fuel filters to reduce the parsed in-memory result.

Parameters:
  • year (int)

  • half (int)

  • path (Path)

  • respondents (Sequence[str] | None)

  • fuel_types (Sequence[str] | None)

Return type:

EIAResult