⚡ `energy`¶

Comprehensive U.S. energy data from the Energy Information Administration (EIA) and Mine Safety and Health Administration (MSHA). Covers electricity generation and retail prices, utility operations, power plant inventory, generator capacity changes, fossil fuel production, state energy consumption, natural gas storage, petroleum stocks, crude oil imports, refinery operations, and coal mine production. All state-level tables join with geo.states via state_abbr. EIA API tables use OFFSET pagination against v2 endpoints. Bulk tables (EIA-860, EIA-861, EIA-860M, EIA-814) use TEXT format with transformers that download, extract, and parse XLSX/ZIP archives.

18 datasets · 201 columns

eia_electricity_generation · table¶

EIA API v2 electric power operational data. Monthly electricity generation (thousand MWh), total fuel consumption (MMBtu), fuel consumption for electricity generation (MMBtu), cost per MMBtu, sulfur content, and ash content. Broken down by state, energy source, and sector. One row per state + energy source + sector + year-month. Cross-references geo.states via state_abbr.

Column	Type	Null	Description
`generation_year`	integer	no	Calendar year of the generation period
`generation_month`	integer	no	Calendar month (1-12) of the generation period
`state_abbr`	string	yes	2-letter state abbreviation (e.g., 'CA')
`state_description`	string	yes	Full state name
`energy_source_code`	string	yes	EIA energy source code (e.g., 'COL', 'NG', 'NUC', 'SUN')
`energy_source`	string	yes	Full energy source description
`sector_code`	string	yes	EIA sector code (e.g., '1', '2', '98', '99')
`sector`	string	yes	Sector description (e.g., 'Electric Utility', 'IPP Non-CHP')
`generation_thousand_mwh`	double	yes	Net electricity generation in thousand MWh
`fuel_consumed_total_mmbtu`	double	yes	Total fuel consumed in MMBtu (all purposes)
`fuel_consumed_for_eg_mmbtu`	double	yes	Fuel consumed for electricity generation in MMBtu
`fuel_cost_per_mmbtu`	double	yes	Fuel cost per MMBtu in dollars
`sulfur_content`	double	yes	Sulfur content percentage of fuel
`ash_content`	double	yes	Ash content percentage of fuel

eia_electricity_prices · table¶

EIA API v2 retail electricity sales data. Annual (and optionally monthly) average price (cents/kWh), revenue (million dollars), sales (million kWh), and customer counts by state and sector. One row per state + sector + year (+ month if available). Cross-references geo.states via state_abbr.

Column	Type	Null	Description
`price_year`	integer	no	Calendar year
`price_month`	integer	yes	Calendar month (1-12), null for annual aggregates
`state_abbr`	string	yes	2-letter state abbreviation (e.g., 'CA')
`state_description`	string	yes	Full state name
`sector_code`	string	yes	EIA customer sector code (e.g., 'RES', 'COM', 'IND', 'TRA', 'ALL')
`sector`	string	yes	Sector description (e.g., 'Residential', 'Commercial', 'Industrial')
`avg_price_cents_kwh`	double	yes	Average retail electricity price in cents per kWh
`revenue_million_dollars`	double	yes	Total revenue in million dollars
`sales_million_kwh`	double	yes	Total electricity sales in million kWh
`customers`	integer	yes	Number of customer accounts

eia_utility_annual · table¶

EIA Form 861 annual electric utility survey. Covers all electric utilities, retail power marketers, and energy service providers. Fields include entity type, NERC region, service type, customer counts and sales by sector (residential, commercial, industrial, transportation), revenue, peak demand, and net generation. One row per utility + year. The transformer downloads and parses the annual ZIP archive of XLSX files from EIA. Cross-references geo.states via state_abbr.

Column	Type	Null	Description
`utility_id`	integer	no	EIA utility identifier
`report_year`	integer	no	Report year
`utility_name`	string	yes	Utility company name
`entity_type`	string	yes	Entity type code (e.g., 'C', 'I', 'M', 'S', 'F', 'G', 'P', 'Q', 'W')
`state_abbr`	string	yes	2-letter state abbreviation (e.g., 'CA')
`ba_code`	string	yes	Balancing authority code
`nerc_region`	string	yes	NERC reliability region code
`service_type`	string	yes	Service type (Bundled, Energy, Delivery)
`data_type`	string	yes	Data type indicator
`activity_generation`	boolean	yes	Whether utility engages in generation
`activity_transmission`	boolean	yes	Whether utility engages in transmission
`activity_distribution`	boolean	yes	Whether utility engages in distribution
`customers_residential`	integer	yes	Number of residential customer accounts
`customers_commercial`	integer	yes	Number of commercial customer accounts
`customers_industrial`	integer	yes	Number of industrial customer accounts
`customers_transportation`	integer	yes	Number of transportation customer accounts
`customers_total`	integer	yes	Total number of customer accounts
`sales_residential_mwh`	double	yes	Electricity sales to residential customers in MWh
`sales_commercial_mwh`	double	yes	Electricity sales to commercial customers in MWh
`sales_industrial_mwh`	double	yes	Electricity sales to industrial customers in MWh
`sales_transportation_mwh`	double	yes	Electricity sales to transportation customers in MWh
`sales_total_mwh`	double	yes	Total electricity sales in MWh
`revenue_residential_thousand`	double	yes	Revenue from residential customers in thousands of dollars
`revenue_commercial_thousand`	double	yes	Revenue from commercial customers in thousands of dollars
`revenue_industrial_thousand`	double	yes	Revenue from industrial customers in thousands of dollars
`revenue_total_thousand`	double	yes	Total revenue in thousands of dollars
`summer_peak_demand_mw`	double	yes	Summer peak demand in MW
`winter_peak_demand_mw`	double	yes	Winter peak demand in MW
`net_generation_mwh`	double	yes	Net electricity generation in MWh

eia_power_plants · table¶

EIA Form 860 annual electric generator inventory. One row per generator (plant + generator ID + year). Includes plant and utility identifiers, geographic location (state, county, city, lat/lon), NERC region, balancing authority, technology, prime mover, energy sources, capacity (nameplate, summer, winter, minimum load), ownership type, operating status, operating and retirement dates, and energy storage flag. Transformer downloads and parses the annual ZIP archive from EIA. Cross-references geo.states via state_abbr; joins eia_utility_annual via utility_id.

Column	Type	Null	Description
`plant_id`	integer	no	EIA plant identifier
`generator_id`	string	no	Generator identifier within the plant
`report_year`	integer	no	Report year
`plant_name`	string	yes	Plant name
`utility_id`	integer	yes	EIA utility identifier (links to eia_utility_annual)
`utility_name`	string	yes	Utility company name
`state_abbr`	string	yes	2-letter state abbreviation (e.g., 'CA')
`county_name`	string	yes	County name
`county_fips`	string	yes	5-digit county FIPS code
`city`	string	yes	City or town name
`latitude`	double	yes	Plant latitude
`longitude`	double	yes	Plant longitude
`nerc_region`	string	yes	NERC reliability region
`balancing_authority_code`	string	yes	Balancing authority code
`balancing_authority_name`	string	yes	Balancing authority name
`primary_purpose_naics`	integer	yes	Primary purpose NAICS code
`regulatory_status`	string	yes	Regulatory status (e.g., Regulated, Nonutility)
`sector_code`	integer	yes	EIA sector code
`sector`	string	yes	Sector description
`technology`	string	yes	Generation technology (e.g., 'Conventional Steam Coal', 'Onshore Wind Turbine')
`prime_mover`	string	yes	Prime mover code (e.g., 'ST', 'GT', 'IC', 'WT', 'PV')
`energy_source_1`	string	yes	Primary energy source code
`energy_source_2`	string	yes	Secondary energy source code
`energy_source_3`	string	yes	Tertiary energy source code
`nameplate_capacity_mw`	double	yes	Nameplate (installed) capacity in MW
`net_summer_capacity_mw`	double	yes	Net summer capacity in MW
`net_winter_capacity_mw`	double	yes	Net winter capacity in MW
`minimum_load_mw`	double	yes	Minimum load in MW
`ownership_code`	string	yes	Ownership type code
`operating_status`	string	yes	Operating status code
`operating_month`	integer	yes	Month generator began commercial operation
`operating_year`	integer	yes	Year generator began commercial operation
`planned_retirement_month`	integer	yes	Planned retirement month
`planned_retirement_year`	integer	yes	Planned retirement year
`energy_storage_flag`	boolean	yes	Whether generator includes energy storage capability

eia_capacity_changes · table¶

EIA Form 860M monthly generator inventory snapshot for December of each year. Captures planned additions and planned retirements with capacity (nameplate, summer, winter, energy storage). One row per generator change record per snapshot. The December file provides the most complete annual picture; prior months may be fetched for intra-year pipeline analysis. Transformer parses the XLSX directly. Cross-references geo.states via state_abbr; joins eia_power_plants via plant_id.

Column	Type	Null	Description
`plant_id`	integer	no	EIA plant identifier
`generator_id`	string	no	Generator identifier within the plant
`snapshot_year`	integer	no	Year of the monthly snapshot file
`snapshot_month`	integer	no	Month of the monthly snapshot file (12 for December)
`change_type`	string	no	Type of capacity change (e.g., 'Planned Addition', 'Planned Retirement', 'New Unit')
`change_year`	integer	yes	Year the change is expected to take effect
`change_month`	integer	yes	Month the change is expected to take effect
`plant_name`	string	yes	Plant name
`entity_id`	integer	yes	EIA entity (utility/owner) identifier
`entity_name`	string	yes	Entity name
`state_abbr`	string	yes	2-letter state abbreviation (e.g., 'CA')
`county_name`	string	yes	County name
`balancing_authority_code`	string	yes	Balancing authority code
`sector`	string	yes	Sector description
`technology`	string	yes	Generation technology
`energy_source_code`	string	yes	Primary energy source code
`prime_mover_code`	string	yes	Prime mover code
`nameplate_capacity_mw`	double	yes	Nameplate capacity in MW
`net_summer_capacity_mw`	double	yes	Net summer capacity in MW
`net_winter_capacity_mw`	double	yes	Net winter capacity in MW
`nameplate_energy_capacity_mwh`	double	yes	Nameplate energy capacity in MWh (for storage units)

eia_fossil_fuel_production · table¶

EIA API v2 petroleum crude oil production by state and month. The transformer also fetches the EIA natural gas production summary endpoint internally and unions both series into the output, so each partition contains both crude oil and natural gas rows distinguished by the fuel_type column. One row per EIA area + fuel type + process + year-month. Cross-references geo.states via state_abbr.

Column	Type	Null	Description
`production_year`	integer	no	Calendar year of production
`production_month`	integer	no	Calendar month (1-12) of production
`eia_area_code`	string	yes	EIA area/region code (may be state abbreviation or PADD code)
`state_abbr`	string	yes	2-letter state abbreviation (e.g., 'CA')
`fuel_type`	string	no	Fuel type ('crude_oil' or 'natural_gas')
`process_code`	string	yes	EIA process code identifying the production activity
`process_name`	string	yes	Process description
`production_volume`	double	yes	Production volume in units specified by production_unit
`production_unit`	string	yes	Unit of measure (e.g., 'Thousand Barrels', 'Million Cubic Feet')
`series_id`	string	yes	EIA time series identifier
`series_description`	string	yes	Full series description

eia_state_energy_consumption · table¶

EIA API v2 State Energy Data System (SEDS). Annual energy consumption, expenditure, and price by state, sector, fuel type, and MSN (energy series code). The MSN code encodes fuel, sector, and metric in a compact 5-character string. The transformer decodes MSN values and maps them to human-readable sector, fuel_type, units, consumption_bbtu, expenditure_million, and price_per_mmbtu columns where applicable. One row per state + MSN + year. Cross-references geo.states via state_abbr.

Column	Type	Null	Description
`year`	integer	no	Calendar year (partition column)
`consumption_year`	integer	no	Calendar year
`state_abbr`	string	yes	2-letter state abbreviation (e.g., 'CA')
`state_name`	string	yes	Full state name
`msn`	string	no	EIA Mnemonic Series Name (5-char code, e.g., 'TETCB', 'NGRCB')
`sector`	string	yes	Sector decoded from MSN (e.g., 'Residential', 'Commercial', 'Transportation', 'Total')
`fuel_type`	string	yes	Fuel type decoded from MSN (e.g., 'Natural Gas', 'Coal', 'Petroleum')
`value`	double	yes	Raw numeric value from the API response
`units`	string	yes	Units for the value field
`consumption_bbtu`	double	yes	Energy consumption in billion BTU (null if MSN is not a consumption series)
`expenditure_million`	double	yes	Expenditure in million dollars (null if MSN is not an expenditure series)
`price_per_mmbtu`	double	yes	Price per million BTU (null if MSN is not a price series)
`series_description`	string	yes	Full human-readable description of the SEDS series

eia_natural_gas_storage · table¶

EIA API v2 weekly natural gas underground storage data. Covers working gas, base gas, total gas, injections, and withdrawals by EIA storage region (East, West, Midwest, Mountain, Pacific, South Central, Salt, Non-Salt, National). One row per region + storage type + report date. Useful for gas market signal analysis and year-over-year storage comparison.

Column	Type	Null	Description
`year`	integer	no	Calendar year of the report date (partition column)
`report_date`	string	no	Report date in ISO format (YYYY-MM-DD)
`storage_year`	integer	no	Calendar year of the report date
`storage_week`	integer	no	Week number within the year (ISO week)
`eia_region_code`	string	yes	EIA storage region code (e.g., 'R10', 'R20', 'R30', 'NAT')
`region`	string	yes	Region description (e.g., 'East', 'West', 'National')
`storage_type_code`	string	yes	Storage type code (e.g., 'SAW' = total working gas, 'SAS' = salt, 'SAN' = non-salt)
`storage_type`	string	yes	Storage type description
`volume_bcf`	double	yes	Volume in billion cubic feet
`units`	string	yes	Units for volume (typically 'Bcf')
`series_id`	string	yes	EIA time series identifier

eia_petroleum_stocks · table¶

EIA API v2 weekly petroleum product stocks. Covers crude oil and refined products (gasoline, distillate, jet fuel, residual fuel, etc.) by PADD district and national totals. One row per area + product + process + report date. Supports supply disruption analysis, seasonal inventory tracking, and refinery margin signals.

Column	Type	Null	Description
`report_date`	string	no	Report date in ISO format (YYYY-MM-DD)
`stock_year`	integer	no	Calendar year of the report date
`stock_week`	integer	no	Week number within the year (ISO week)
`eia_area_code`	string	yes	EIA area code (e.g., 'SAE', 'USA', 'PAD1', 'PAD2')
`padd`	string	yes	PADD district description or 'National'
`product_code`	string	yes	EIA petroleum product code (e.g., 'EPC0', 'EPM0', 'EPD0')
`product`	string	yes	Product description (e.g., 'Crude Oil', 'Finished Motor Gasoline')
`process_code`	string	yes	EIA process code identifying the stock measurement
`process_name`	string	yes	Process description
`stocks_kbbl`	double	yes	Stocks in thousand barrels
`series_id`	string	yes	EIA time series identifier
`series_description`	string	yes	Full series description

eia_crude_oil_imports · table¶

EIA Form 814 monthly crude oil import survey. The transformer iterates all 12 monthly XLSX files for the given year (URL pattern impa{yy}{m}.xlsx where yy is 2-digit year and m is 1-based month digit) and unions them into a single partition. One row per import transaction per month (importer + origin country + entry port + receiving refinery). Includes API gravity, sulfur content, and volume in thousand barrels. Cross-references geo.states via state_abbr (refinery state).

Column	Type	Null	Description
`rpt_period`	string	no	Reporting period in YYYYMM format
`import_year`	integer	no	Import year
`import_month`	integer	no	Import month (1-12)
`importer_name`	string	no	Name of the importing company
`origin_country`	string	yes	Country of origin name
`origin_country_code`	integer	no	EIA country code for the origin country
`entry_port_code`	string	yes	PADD district code for the entry port
`entry_port_city`	string	yes	Entry port city name
`entry_padd`	integer	yes	PADD district number of the entry port
`dest_padd`	integer	yes	PADD district number of the destination refinery
`receiving_company`	string	yes	Company receiving the crude at the destination
`refinery_site_id`	integer	no	EIA refinery site identifier
`refinery_site_name`	string	yes	Refinery site name
`refinery_state_abbr`	string	yes	2-letter state abbreviation of the receiving refinery
`api_gravity`	double	yes	API gravity of the imported crude
`sulfur_content_pct`	double	yes	Sulfur content as a percentage by weight
`volume_kbbl`	integer	yes	Volume imported in thousand barrels

eia_refinery_operations · table¶

EIA API v2 petroleum refinery process data in tall format. One row per EIA area + series (process_code) + year-month. Key series include crude inputs to distillation (CRDISS), operable distillation capacity (CAPACITY), and utilization rate (UTIL). Additional series cover catalytic cracking, coking, reforming, and other secondary processes. Pivoting into wide format is done via the refinery_utilization_summary view. One row per area + series_id + report year-month.

Column	Type	Null	Description
`report_year`	integer	no	Calendar year
`report_month`	integer	no	Calendar month (1-12)
`eia_area_code`	string	yes	EIA area code (e.g., PADD code or 'USA')
`padd`	string	yes	PADD district description or 'National'
`series_id`	string	yes	EIA time series identifier
`process_code`	string	yes	EIA refinery process code
`metric_name`	string	yes	Metric description (e.g., 'Crude Oil Input to Atmospheric Crude Oil Distillation Units')
`units`	string	yes	Units of measure (e.g., 'Thousand Barrels per Day')
`value`	double	yes	Metric value

eia_coal_mines · table¶

MSHA MinesProdYearly coal mine production data (pipe-delimited CSV ZIP). The transformer downloads MinesProdYearly.zip and Mines.zip, performs an inner join on mine_id, filters to coal mines (COAL_METAL_IND = 'C'), and returns one row per mine + subunit + year. Includes mine demographics, operator/controller identity, geographic location (lat/lon, county, state), mine type and status, production volume in short tons, employee count, annual hours, labor productivity, and average seam height (underground mines). The transformer filters by the requested year dimension. Cross-references geo.states via state_abbr.

Column	Type	Null	Description
`mine_id`	string	no	MSHA mine identifier
`report_year`	integer	no	Production report year
`mine_name`	string	yes	Mine name
`controller_name`	string	yes	Mine controller company name
`operator_name`	string	yes	Mine operator company name
`state_abbr`	string	yes	2-letter state abbreviation (e.g., 'CA')
`county_fips`	string	yes	5-digit county FIPS code
`county_name`	string	yes	County name
`latitude`	double	yes	Mine latitude
`longitude`	double	yes	Mine longitude
`mine_type`	string	yes	Mine type (e.g., 'Surface', 'Underground')
`subunit_code`	string	no	MSHA subunit code (e.g., '01' = Underground, '02' = Surface, '03' = Auger)
`subunit`	string	yes	Subunit description
`mine_status`	string	yes	Mine status (e.g., 'Active', 'Temporarily Idled', 'Abandoned')
`production_short_tons`	double	yes	Coal production in short tons
`avg_employee_count`	double	yes	Average number of employees
`annual_hours`	double	yes	Total employee hours worked
`labor_productivity`	double	yes	Labor productivity in short tons per employee hour
`avg_mine_height_inches`	double	yes	Average mine height in inches (underground mines only)

state_energy_mix · view¶

Annual renewable and fossil fuel generation mix by state. Aggregates eia_electricity_generation by state and year, computing total generation and generation by broad fuel category (renewables, nuclear, fossil, other). Calculates renewable percentage and fossil percentage for trend analysis. One row per state + year. Joins geo.states for full state name and FIPS.