Integrate the documented FRED V1 observation shape
Map FRED series observations and metadata while distinguishing V1 fixtures, the newer V2 offering, daily vintages and series-specific usage rights.
This publication’s FRED adapter targets the documented V1 series-observations response shape using synthetic fixtures. FRED also documents a V2 bulk-release interface; the fixture adapter does not claim compatibility with that different contract.
Pin the interface you actually implement
The FRED documentation reviewed on 16 October 2026 lists both V1 and V2. V1 provides series-oriented interfaces, while V2 is described for bulk release histories. Name V1 explicitly in the adapter contract and request manifest. A generic label such as latest FRED API would become misleading as interfaces evolve.
The V1 observation endpoint has request parameters for series, output format, observation range and real-time range, among others. Store the selected values explicitly rather than relying on defaults that may change the interpretation of a historical query. A fixture parser does not make a network request and must not imply that a sample credential is valid.
Map a synthetic response in stages
Take an invented item with date 2026-01-01, value string 98.75 and realtime_start 2026-02-12. Validate the envelope and item shape, parse the value under the numeric policy, preserve the source record and assign availability_basis fred_realtime_date. The output’s observation period and availability date remain separate.
If the next synthetic item has a declared missing token, preserve null under the adapter policy rather than converting it to zero. If it has malformed text, return an error. These two fixtures test different paths. Neither fixture reports a real economic observation, and the invented values should never appear in a chart labeled as live FRED data.
Fetch meaning from series metadata
The series metadata endpoint documents fields such as units, frequency, seasonal adjustment and notes. Those fields matter because the observation payload’s numerical value does not explain its economic scale or adjustment. Retain the metadata version or snapshot used for normalization alongside the observation request.
For an invented monthly index of 98.75, unit index and a declared base period have a different meaning from 98.75 percent or USD billions. A transformation request can also change the interpretation. Tests should verify that changing units or frequency assumptions changes the metadata or is rejected, rather than leaving an attractive but mislabeled numeric series.
Keep daily vintage support within its limits
The fixture’s real-time date is daily evidence. Preserve it as a date and retain the request’s vintage-selection context. Do not convert a current response into a complete historical archive by assigning one retrieval time to all past observations or by assuming every desired vintage was returned.
A synthetic acceptance case should include one period with two daily vintages and verify that both survive normalization. A second case should contain conflicting candidates on the same day and require a visible resolution policy. This establishes adapter behavior for retained evidence; it does not certify intraday publication timing or completeness of real provider history.
Separate access and redistribution review
FRED V1 key documentation requires an API key and describes application and user key responsibilities. Its API terms separately preserve third-party series rights and require a non-endorsement notice for applications using the API. A working request is therefore not blanket permission to republish every returned series.
The site’s offline fixtures require no live key and contain invented observations. A real integration must review the exact series notes, provider terms, identity requirements and request policy before use. Retain that review with a date and scope. Passing the sample tests supports the specified parser and normalization path, not an available commercial API product, provider endorsement or a lawful right to redistribute an arbitrary dataset.
Keep in the decision record
- Target the documented V1 shape explicitly; V2 is a separate interface.
- Join observations to their units, frequency and adjustment metadata.
- Treat API access and series redistribution rights as separate requirements.
Source notes
- FRED API — V1 and V2 documentation landing page, reviewed 16 October 2026
- FRED API V1 — Series observations
- FRED API V1 — Series metadata
- FRED API V1 — API Keys
- FRED — API Terms of Use
Primary specifications support the interface descriptions. All downloadable response fixtures are synthetic. Access and rights checks are dated in the source inventory.
Continue the analysis
Store revisions as evidence instead of overwriting history
Distinguish changed values, repeated retrievals and conflicting source identities while preserving the version that a research decision used.
Parse numbers only after specifying their units
Handle numeric strings, finite values, percentage scales and magnitude conversions with explicit, testable transformation rules.
Review data rights at the dataset and output level
Distinguish API access, underlying data permissions, attribution and redistribution, while preserving a documented World Bank terms-link gap.
Version 1 · Published 16 October 2026. Inspect the method · Open the contract lab