FRED and BLS API Time-Series Plotting
Economic plotting is a data-contract problem before it is a charting problem: identity, frequency, units, adjustment, missingness, and revision status determine the claim.
Combinatorial structure, time series, transit flows, and compute systems sharing one visual grammar.
Interactive model
Raw scale vs indexed comparison
Toggle indexed and raw scale views to see why economic series often need normalization before comparison.
Live HTML simulation · adjust the controls and watch the computed output respond.
Interactive
Normalization lets unlike economic series share a visual frame
This is a simplified teaching model. Its displayed values are computed from the controls; the article explains where the model stops.
Site connection
The Economic Series Plotter fetches FRED and BLS data and turns it into consistently formatted charts for FED Challenge analysis.
The Plot Is the Last Step
A defensible chart preserves what each observation means. The same line shape can represent a level, index, percent, annualized change, or seasonally adjusted statistic; consistent colors cannot repair incompatible definitions.
FRED and BLS Expose Different Data Contracts
FRED is maintained by the Federal Reserve Bank of St. Louis and aggregates series from many sources. Its API supports series metadata, observations, releases, real-time periods, and vintage dates. BLS is the primary publisher for many labor, price, wage, productivity, and employment series; its v2 API accepts one or more series IDs and can return catalog metadata, calculations, annual averages, and aspects when requested under supported conditions.
The project source establishes only that the Economic Series Plotter calls FRED and BLS APIs and charts results with Matplotlib, Seaborn, and Streamlit for consistent FED Challenge use. It does not document specific series IDs, transformations, vintage handling, cache policy, or validation results.
| Field in a normalized record | Purpose |
|---|---|
| provider + series_id | Stable identity and lookup path |
| observation_date + value | The measured period and parsed number |
| frequency + units | Interpret spacing and magnitude |
| seasonal_adjustment | Prevent adjusted/unadjusted confusion |
| title + source/agency | Human meaning and provenance |
| retrieved_at + vintage/realtime window | Reproduce what was known when |
| status + footnotes | Preserve preliminary, revised, or special values |
Parsing Is Part of the Analysis
API success means the envelope was returned, not that every requested series is valid. Check provider status and messages, then validate each series ID, observation date, numeric value, and requested window. FRED can represent missing observation values with a period; BLS responses include period codes, latest flags, and footnotes. Missing is null, never zero.
BLS monthly records use period codes such as M01 through M12, while M13 can represent an annual average in relevant outputs and should not be plotted as a thirteenth month. Sort by actual period, deduplicate deliberately, and keep raw payload references so parser decisions remain auditable.
Analogy limit: a series ID resembles a stock ticker because it is a compact identifier. Unlike a ticker, it may encode survey, population, area, measure, adjustment, and other dimensions; a similar label does not imply a comparable statistic.
Transformations Must Answer a Named Question
Raw levels are best when the unit itself matters. Indexing each series to 100 at a shared valid base date compares cumulative relative movement. Percent change answers growth over an interval; year-over-year change compares a period with the same period one year earlier and can reduce recurring seasonality, though it does not replace an official seasonal-adjustment method.
Do not put CPI index points, an unemployment percentage, and a policy rate on one unlabeled scale. Use separate panels or clearly labeled axes when levels matter. If indexing, state the base date and exclude series without a valid base observation rather than silently choosing a different date for each.
| Transformation | Formula or rule | Question |
|---|---|---|
| Raw level | x_t | What was the reported level? |
| Indexed | 100 × x_t / x_base | How far has each series moved from one common base? |
| Period change | 100 × (x_t/x_{t-k} - 1) | How fast did it change over k periods? |
| Rolling mean | Mean of a declared trailing window | What is the local trend after smoothing? |
| Separate panels | Shared time axis, independent units | How did unlike measures co-move without erasing units? |
Worked Example
Take two illustrative monthly series on a shared valid base month. Series A rises from 200 to 210, so its index moves from 100 to 105. Series B falls from 4.0 to 3.8, so its index moves from 100 to 95. The indexed chart shows +5% versus -5% movement, but it does not make their raw units interchangeable.
For a separate inflation-style example, an index moving from 300 in May last year to 309 this May has year-over-year change 100×(309/300−1)=3%. If last May is missing, the correct output is missing, not zero or a comparison against June. All values here are illustrative and are not observations or results reported by the Economic Series Plotter.
| Illustrative series | Base | Later | Indexed later |
|---|---|---|---|
| A | 200 | 210 | 105 |
| B | 4.0 | 3.8 | 95 |
| Interpretation | Both start at 100 | Units remain different | Relative movement only |
Revisions, Vintages, and Reproducibility
Economic observations can be revised. FRED's vintage-date and real-time-period facilities let an analyst distinguish the latest value from what was available at an earlier date. A policy briefing recreated months later may change if it silently fetches the newest revision.
Store the request parameters, retrieval timestamp, raw response hash, provider metadata, transformation configuration, and chart code version. Label preliminary observations and decide whether the product shows latest-vintage analysis or an as-of historical view.
Chart Validation
Before rendering, assert monotonic dates, expected frequency, unit compatibility, adjustment compatibility, missing-value counts, and enough history for the transformation. After rendering, confirm that titles, axes, legends, base period, notes, and source labels describe the actual data rather than defaults.
Use fixture responses containing a missing FRED value, BLS M13, a preliminary footnote, duplicate periods, and a provider-level error. A screenshot test can catch layout regression but cannot prove the economic transformation is correct; test the output table numerically first.
Common Pitfalls
- Mixing seasonally adjusted and non-adjusted series without disclosure.
- Plotting unlike units on one scale and letting visual proximity imply comparability.
- Treating missing observations or provider error payloads as zero.
- Ignoring revisions, vintage dates, preliminary flags, and footnotes.
- Treating BLS annual-average period M13 as a calendar month.
- Indexing each series from a different silent base date.
- Inventing project transformations or results not documented in the source.