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:
objectNormalized observations and sanitized request provenance for all pages.
- Parameters:
frame (DataFrame)
requests (tuple[RequestRecord, ...])
- 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
valuebecomes numeric and its untouched representation is retained assource_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.
timestampis a UTC month label for indexing, not an assertion about the plant’s reporting timezone.reporting_monthretains the source label. AggregatedALLcategories 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 Hourand only unadjusted fuel columns. Source headers label hourly average power as MW. Multiplication by the explicit one-hour interval gives MWh;source_unitretainsMW. 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:
objectEIA 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:
- 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 orUS48explicitly. 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:
- 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:
- 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: