Crate ferric_fred

Expand description

ferric-fred — a strongly-typed async Rust client for the FRED API (Federal Reserve Economic Data, from the Federal Reserve Bank of St. Louis).

The client covers all of FRED’s read endpoints — series, observations, search, categories, releases, sources, tags, and the release table tree — behind ergonomic async builders, with newtype identifiers, typed enums for FRED’s closed value sets, and a typed Error taxonomy that never panics on a network or parse failure. Paginated endpoints can be walked to exhaustion with Paginate::send_all or streamed lazily with Paginate::stream. See the design ADRs under docs/adr/ for the decisions that shape the API.

§Feature flags

schemars (off by default) — derive schemars::JsonSchema on the public return types, so a consumer (the bundled MCP server, say) can advertise the exact shape an endpoint returns. Additive; plain consumers pay nothing. See ADR-0023.

use ferric_fred::{Client, Paginate, SeriesId};

let client = Client::from_env()?; // reads FRED_API_KEY

// One series' observations:
let observations = client.observations(&SeriesId::new("GNPCA")).send().await?;
println!("{} observations", observations.len());

// Search, paged to exhaustion (or `.stream()` for lazy iteration):
let matches = client.search("unemployment rate").send_all().await?;
println!("{} matching series", matches.len());

Structs§

Category: A node in the FRED category tree (the fred/category and fred/category/children endpoints).
CategoryId: A FRED category identifier — a numeric node in the category tree (the root is CategoryId::ROOT, id 0).
Client: An async client for the FRED API.
Observation: A single observation in a FRED series: a calendar date, its value, and the real-time period that value was current for (ALFRED — ADR-0024).
ObservationsRequest: A builder for an observations request, returned by Client::observations.
Release: A FRED data release — a publication such as “Gross Domestic Product”, from the fred/release and fred/releases endpoints.
ReleaseDate: A single scheduled or historical release date, from the fred/releases/dates and fred/release/dates endpoints — the date a release was (or is scheduled to be) published.
ReleaseDatesRequest: A builder for the release-date endpoints, returned by Client::releases_dates (fred/releases/dates, the publication dates of every release) and Client::release_dates (fred/release/dates, the dates of one release). Both share optional sort, paging, and the “include dates with no data” toggle and return ReleaseDatesResults; release_dates additionally carries the release_id. Finish with send.
ReleaseDatesResults: A page of release dates with pagination metadata, shared by the fred/releases/dates and fred/release/dates endpoints.
ReleaseElementId: A FRED release-table element identifier — the numeric id of a node in a release’s table tree (a section, table, or series row; see fred/release/tables).
ReleaseId: A FRED release identifier — the numeric id of a data release (a publication such as “Gross Domestic Product”).
ReleaseTable: A release’s table tree, from the fred/release/tables endpoint — the layout a release uses to present its series (sections and tables, with series rows nested beneath them).
ReleaseTableElement: A node in a release’s table tree: a section, a table, or a series row. Nodes nest via children to arbitrary depth.
ReleaseTablesRequest: A builder for a release/tables request, returned by Client::release_tables. Fetches a release’s table tree — the whole tree by default, or the subtree rooted at one element via element. Finish with send.
ReleasesRequest: A builder for the release-listing endpoints, returned by Client::releases (fred/releases, all data releases) and Client::source_releases (fred/source/releases, the releases of one source). Both share optional sort and paging and return ReleasesResults; source_releases additionally carries the source_id. Finish with send.
ReleasesResults: A page of releases with pagination metadata, from the fred/releases endpoint.
Series: Metadata describing a FRED series (the fred/series endpoint).
SeriesId: A FRED series identifier, e.g. GNPCA or UNRATE.
SeriesListRequest: A builder for the FRED endpoints that return a page of series filtered by a single facet: category/series, release/series, and tags/series. They share the same optional ordering and paging and all return SeriesSearchResults; they differ only in the endpoint path and the one facet parameter (category_id / release_id / tag_names).
SeriesSearchRequest: A builder for a series/search request, returned by Client::search.
SeriesSearchResults: A page of series/search results: the matching series plus FRED’s pagination metadata. count is the total number of matches across all pages, not just this one — use it with offset/limit to page.
SeriesUpdatesRequest: A builder for a series/updates request, returned by Client::series_updates. Lists the series updated most recently (ordered by last-updated time), optionally narrowed to a class of series. Finish with send.
Source: A FRED data source — the organization that produces releases (e.g. the Bureau of Economic Analysis), from the fred/source and fred/sources endpoints.
SourceId: A FRED source identifier — the numeric id of a data source (the organization that produces a release, e.g. the Bureau of Economic Analysis).
SourcesRequest: A builder for a sources request, returned by Client::sources. Lists all FRED data sources, with optional sort and paging. Finish with send.
SourcesResults: A page of sources with pagination metadata, from the fred/sources endpoint.
Tag: A FRED tag — a keyword used to classify series (e.g. gdp, quarterly, nsa), from the fred/tags, fred/series/tags, and related endpoints.
TagsRequest: A builder for the tag-listing endpoints — the whole-vocabulary pair Client::tags (fred/tags) / Client::related_tags (fred/related_tags), and the scoped variants that list the tags of one category, release, or series search: Client::category_tags, Client::category_related_tags, Client::release_tags, Client::release_related_tags, Client::series_search_tags, and Client::series_search_related_tags.
TagsResults: A page of tags with pagination metadata, from the fred/tags and fred/series/tags endpoints.
VintageDates: The vintage dates of a series with pagination metadata, from the fred/series/vintagedates endpoint.
VintageDatesRequest: A builder for a series/vintagedates request, returned by Client::series_vintagedates. Lists the dates on which a series was revised or newly released, with optional sort and paging. Finish with send.

Enums§

AggregationMethod: How observations are aggregated when down-sampling to a lower frequency (the aggregation_method request parameter). Only meaningful alongside ObservationsRequest::frequency.
Error: Errors returned by the ferric-fred client.
Frequency: The native reporting frequency of a FRED series.
OrderBy: Field to order series/search results by (the order_by request parameter). Request-only, so it carries query_code and is #[non_exhaustive] but has no Other variant.
SearchType: How series/search interprets the search text (the search_type request parameter).
SeasonalAdjustment: Whether, and how, a FRED series is seasonally adjusted.
SortOrder: Sort order for returned observations, by observation date (the sort_order request parameter).
Units: A units transformation FRED applies to a series’ observations before returning them (the units request parameter).
UpdatesFilter: Which series series/updates returns, by FRED’s filter_value parameter.

Traits§

Page: One page of results from a paginated FRED endpoint.
Paginate: A request builder for a paginated FRED endpoint.

Type Aliases§

Result: A Result whose error type is this crate’s Error.