Energy Mechanics renders the U.S. energy system as schematic diagrams wired to live data. Pipe widths, tank levels, and Sankey ribbons are scaled directly to the underlying observations — nothing is drawn by eye. Every domain (petroleum, natural gas, electricity, total energy) has an overview schematic plus deep-dive pages for the nodes that warrant it.
Built as a single static site. The repository ships an
update_data.py script that runs in a GitHub Action, pulls fresh
observations from the EIA v2 API, writes a single data.json file, and
commits the change. Every schematic reads that one file on page load. No
databases, no servers, no tracking.
| Domain | Source | Cadence |
|---|---|---|
| Petroleum — weekly | EIA Weekly Petroleum Status Report (WPSR) — flows, stocks, refinery inputs, PADD breakdowns, WTI Cushing daily spot | Weekly (Wed ~10:30 ET) |
| Petroleum — monthly | EIA Petroleum Supply Monthly — crude imports by country, exports by destination | Monthly (~end of month) |
| Natural gas — flows | EIA Natural Gas Monthly (NGM) — production, consumption by sector, LNG/pipeline exports, imports | Monthly (~last business day) |
| Natural gas — storage | EIA Weekly Natural Gas Storage Report (WNGSR) — working gas in underground storage, by region (R31 East … R48 Lower 48) | Weekly (Thu 10:30 ET) |
| Natural gas — price | Henry Hub daily spot, EIA price series | Daily |
| Electricity — generation | EIA Electric Power Monthly (EPM) — net generation by fuel type, retail sales by sector, solar utility/distributed split, top states for each major fuel | Monthly (~25th) |
| Electricity — capacity | EIA Form 860 via the operating-generator-capacity endpoint — nameplate capacity per fuel, summed across all operating generators | Monthly (Form 860M) |
| Total energy | EIA Monthly Energy Review (MER) — primary-energy consumption by source, in quads. Sankey flow structure from Lawrence-Livermore's annual U.S. energy flow chart. | Monthly + Annual |
| Drilling rigs | EIA Drilling Productivity Report (DPR) — monthly rig counts by basin, used as a stand-in for Baker Hughes' weekly count (which has no public JSON API) | Monthly |
The data refresh job runs every Thursday at 14:00 UTC and again at
18:00 UTC — two attempts so that holiday-delayed WPSR releases (when a
federal holiday falls Mon-Wed) still get caught the same week. Every push to
main also re-deploys the site, with cache-busting query strings so
browsers pick up updated assets immediately.
Many readouts show a "5-yr range" badge — that's the min/avg/max of the same ISO-week-of-year (for weekly series) or same calendar month (for monthly series) across the previous five calendar years. Tells you whether the current observation is above, within, or below seasonal norms, which is more useful than a rolling-average comparison for highly seasonal energy data.
Electricity generation, retail sales, and MER consumption are reported monthly but with strong seasonal swings. We show trailing-12-month sums so headline numbers track annual-rate magnitudes that update smoothly each month rather than swinging seasonally. The 5-year range bands on these readouts use the same-month rolling-annual values across prior years.
The Total Energy Sankey shows wind/solar/hydro at smaller magnitudes than Lawrence-Livermore's published chart. Both are correct under different methodologies. EIA's MER reports the actual BTU content of renewable electricity (1 kWh ≈ 3,412 BTU). LLNL applies a "fossil-fuel equivalent" multiplier (~2.78×) representing how much fossil energy would have been consumed to generate the same electricity at thermal-plant efficiency.
Our Sankey uses MER actuals — the more honest representation, since a kWh of wind doesn't displace 3 kWh of coal, it displaces 1 kWh of whatever the marginal generator is. That makes the renewables ribbons look small relative to LLNL's chart even though total U.S. wind generation is ~470 TWh/year. Fossil sources and nuclear use the same heat-content convention in both, so those magnitudes match.
Each individual API call is wrapped in a try/except: if a single series ID is wrong, that key falls back to its previous value (or to a seeded LLNL/EIA estimate on a fresh repo). The page stays populated; the workflow log shows which series failed so they can be fixed in the next iteration. Status badges flip from "LIVE ✓" to "CACHED" when nothing resolved this run.
Before writing data.json, a verify function checks every key against plausible-range bounds (e.g. WTI ∈ [$10, $400], total U.S. primary energy ∈ [60, 140] quads, refinery utilization ∈ [50, 102]%). If anything fails, the script exits non-zero and the previous data.json stays in place — so a single bad API response can't overwrite good data with junk. Live-status keys get stricter validation than seeded keys.
A 51d5d015 placeholder in every HTML page is replaced with the
deploy SHA at build time and appended to asset URLs as a query string.
Browsers re-fetch assets when the SHA changes (every deploy) but cache
normally between deploys. The data.json fetch is always
cache: 'no-store' so freshness isn't gated on browser cache TTL.
Built by Second Order Edge. Code is open source on GitHub. All data is from the U.S. Energy Information Administration (public domain) and Lawrence Livermore National Laboratory (public domain). No copyrighted content is rehosted; all figures are computed from primary EIA observations.
Bugs, suggestions, or wrong series IDs: file an issue on GitHub.