Interactive Petroleum Inventory Seasonality Charts

Purpose

This visualization answers one question at a glance: is the current level of U.S. petroleum inventories normal, or not?

Inventories — how much crude, gasoline, and diesel the country has in storage — are one of the clearest early signals of strain in the energy system. Plenty of cushion means the market can absorb a shock; stocks near the bottom of their range mean less room for error, and price starts doing the work inventory no longer can.

The catch is that "normal" is seasonal. Stocks naturally rise and fall every year — gasoline builds ahead of summer driving, distillate ahead of winter heating — so a raw number tells you little on its own. The same level can be alarming in one month and ordinary in another. To know if today is unusual, you have to compare it to the same point in prior years.

That's what this tool does. By laying every year on a common week-1-to-52 axis, it shows the normal seasonal rhythm as a backdrop and lets you see exactly where the current year falls against it — and now, where each decade fell against one another.

The data source

All inventory figures come from the U.S. Energy Information Administration (EIA), the statistical arm of the U.S. Department of Energy. The data is free, public, and updated weekly. We use four weekly stock series:

Series IDProductHistoryWCRSTUS1Crude oil1982–presentWGTSTUS1Total gasoline1990–presentWDISTUS1Distillate fuel oil / diesel1982–presentWCSSTUS1Strategic Petroleum Reserve (SPR)1982–present

All values are reported in thousands of barrels. We do not alter, smooth, or adjust the underlying figures.

What changed from V1: live API retrieval

In the original version, data was downloaded manually as Excel files from eia.gov and read from disk. V2 fetches data directly from the EIA API on each run, eliminating the manual download step.

The API endpoint used is:

https://api.eia.gov/v2/petroleum/stoc/wstk/data/

Each series is requested with frequency=weekly, sorted oldest-first, and up to 5,000 records — sufficient to cover the full history of all four series.

This means the chart always reflects the most recent EIA release without any manual file management. The tradeoff is a network dependency: the script requires an active internet connection and a valid API key.

Step 1 — Start with what the EIA already gives you

The EIA publishes each series as a single long time series: one continuous line from the 1980s to today. It's accurate and complete, but built to show the long arc, not the current moment. Everything we do from here is reorganization, not new data.

Step 2 — Reshape the timeline into weeks-of-the-year

Instead of plotting time continuously, we split each year into its own track and align them on a common 1-to-52 week axis. For every weekly observation we compute its week-of-year and group readings by calendar year.

Week-of-year is defined as:

week = ((day_of_year − 1) ÷ 7) + 1,  capped at 52

This keeps a consistent week-to-week position across all years. The result: instead of one long line, we get one line per year, all overlaid on the same axis. This is the core move — we changed the shape, not the substance.

Step 3 — Handle data quirks

Real weekly data isn't perfectly clean, so two small rules apply:

• When the day-of-year math places two readings in the same week bucket, we average them.
• When a week bucket has no reading, we leave a gap rather than inventing a value.

These choices effect at most a handful of points per year and don't change the shape of any line.

Step 4 — Color by decade (new in V2)

The original version rendered all prior years as faint grey lines. V2 groups years by decade and assigns each decade a distinct color, with lines within a decade fading from a lighter shade (oldest year) to a darker shade (most recent year in that decade). The current year remains a bold red line drawn on top.

The decade palette:

DecadeColor1980sGray1990sGreen2000sBlue2010sOrange2020sPurpleCurrent yearRed (bold)

Within each decade, the per-year shade is interpolated linearly between a light end and a dark end based on the year's position in that decade. This preserves the historical "envelope" reading from V1 while adding a new layer of information: readers can now see whether the pattern shifted between decades, not just between years.

Step 5 — Interactive controls (new in V2)

V2 adds one control above the chart:

Decade toggle pills — each decade appears as a clickable pill. Toggling a decade off hides all of its year-lines from the chart and dims the corresponding legend swatch. This lets readers isolate specific eras — for example, showing only the 2010s and 2020s together — without the chart becoming unreadable. All decades are active by default.

Step 6 — Hover interactivity

Hovering over any line shows the year, week number, and stock level in thousands of barrels. This is unchanged from V1: it turns the chart from something you look at into something you investigate.

Updating

We run the script to regenerate the output HTML. Because data is fetched live from the EIA API, no file downloads or manual steps are needed — just run the script and the output reflects the latest weekly release. The current-year highlight and all date ranges update automatically.

Honest notes and limitations

• Week-of-year is a simplification. The (day_of_year ÷ 7) method gives each week a stable position across years, but EIA's actual report dates are Fridays and don't align perfectly week-to-week. An alternate convention (ISO weeks, or EIA's own week numbering) would shift a few points by one position. It does not change any line's overall shape or the story it tells.
• Weekly figures are EIA estimates and get revised. EIA's weekly numbers are timely estimates; they are periodically revised and later reconciled against more complete monthly data. We use the weekly series for currency and accept that recent points may move slightly in later releases.
• History lengths differ by product. Gasoline begins in 1990; crude, distillate, and SPR go back to 1982. The gasoline chart has fewer historical lines — not an error, just the limit of the public record.
• Decade coloring is a grouping convenience, not a claim. Assigning color by decade is a visual shorthand. Decade boundaries are calendar-based (1980, 1990, …) and don't correspond to any market regime or structural break. Readers should draw their own conclusions about whether decade-level patterns are meaningful for a given series.
• We did not invent the data. Every number is the EIA's. Our contribution is the reorganization — the seasonal framing, the decade coloring, and the interactivity — not the underlying figures.