Struct Client 

pub struct Client { /* private fields */ }

An async client for the FRED API.

Cheap to clone — the underlying reqwest::Client holds a connection pool behind an Arc, so clones share it.

Implementations

impl Client

pub fn new(api_key: impl Into<String>) -> Result<Self>

Build a client with the given FRED API key.

Errors

Returns an error if the underlying HTTP client cannot be built.

pub fn from_env() -> Result<Self>

Build a client, reading the API key from the FRED_API_KEY environment variable.

Errors

Returns Error::InvalidInput if FRED_API_KEY is unset, or an error if the underlying HTTP client cannot be built.

pub fn observations(&self, series_id: &SeriesId) -> ObservationsRequest<'_>

Begin an observations request for a series.

Returns a builder; set optional parameters (date range, units transform, frequency aggregation, sort order, paging) and call ObservationsRequest::send to run it. With nothing set, FRED’s defaults apply (full history, levels, ascending by date).

use ferric_fred::{SeriesId, Units};
let obs = client
    .observations(&SeriesId::new("GNPCA"))
    .units(Units::PercentChange)
    .limit(10)
    .send()
    .await?;

pub async fn series(&self, series_id: &SeriesId) -> Result<Series>

Fetch metadata for a series (the fred/series endpoint).

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub fn search(&self, search_text: impl Into<String>) -> SeriesSearchRequest<'_>

Begin a search over series (the fred/series/search endpoint).

Returns a builder; set optional parameters (search type, ordering, sort, paging) and call SeriesSearchRequest::send to run it.

use ferric_fred::OrderBy;
let results = client
    .search("industrial production")
    .order_by(OrderBy::Popularity)
    .limit(5)
    .send()
    .await?;
println!("{} matches", results.count);

pub fn series_search_tags( &self, search_text: impl Into<String>, ) -> TagsRequest<'_>

Begin a request for the tags on the series matching a search (the fred/series/search/tags endpoint) — the tag facets of a full-text search, for narrowing it down.

Returns a TagsRequest builder; set optional tag-filter text (sent as FRED’s tag_search_text), sort, and paging, then call send to run it.

let results = client.series_search_tags("unemployment").limit(10).send().await?;
println!("{} tags", results.count);

pub fn series_search_related_tags<I, S>( &self, search_text: impl Into<String>, tag_names: I, ) -> TagsRequest<'_>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Begin a request for the tags that co-occur, among the series matching a search, with a seed set of tags (the fred/series/search/related_tags endpoint).

Accepts any iterable of seed tag names (joined with ; for FRED). Returns a TagsRequest builder; set optional tag-filter text (sent as tag_search_text), sort, and paging, then call send to run it.

let results = client
    .series_search_related_tags("unemployment", ["monthly"])
    .send()
    .await?;
println!("{} related tags", results.count);

pub async fn category(&self, category_id: CategoryId) -> Result<Category>

Fetch a single category by id (the fred/category endpoint). Use CategoryId::ROOT for the top of the tree.

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub async fn category_children( &self, category_id: CategoryId, ) -> Result<Vec<Category>>

Fetch the child categories of a category (the fred/category/children endpoint) — the primary way to walk the category tree downward.

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub async fn category_related( &self, category_id: CategoryId, ) -> Result<Vec<Category>>

Fetch the categories related to a category (the fred/category/related endpoint) — cross-links to sibling topics elsewhere in the tree, distinct from the parent/child hierarchy. FRED returns the full list unpaginated, so this yields a plain Vec<Category> (often empty).

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub fn category_series(&self, category_id: CategoryId) -> SeriesListRequest<'_>

Begin a request for the series in a category (the fred/category/series endpoint).

Returns a SeriesListRequest builder; set optional ordering/paging and call send to run it.

use ferric_fred::CategoryId;
let results = client
    .category_series(CategoryId::new(125))
    .limit(5)
    .send()
    .await?;
println!("{} series", results.count);

pub fn category_tags(&self, category_id: CategoryId) -> TagsRequest<'_>

Begin a request for the tags used by the series in a category (the fred/category/tags endpoint) — the tag facets available when browsing a category.

Returns a TagsRequest builder; set optional tag-filter text/sort/ paging and call send to run it.

use ferric_fred::CategoryId;
let results = client.category_tags(CategoryId::new(125)).limit(10).send().await?;
println!("{} tags", results.count);

pub fn category_related_tags<I, S>( &self, category_id: CategoryId, tag_names: I, ) -> TagsRequest<'_>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Begin a request for the tags that co-occur, within a category, with a seed set of tags (the fred/category/related_tags endpoint) — refine a category browse by discovering adjacent tags.

Accepts any iterable of seed tag names (joined with ; for FRED). Returns a TagsRequest builder; set optional tag-filter text/sort/ paging and call send to run it.

use ferric_fred::CategoryId;
let results = client.category_related_tags(CategoryId::new(125), ["gdp"]).send().await?;
println!("{} related tags", results.count);

pub fn releases(&self) -> ReleasesRequest<'_>

Begin a request listing all FRED data releases (the fred/releases endpoint) — a browse axis parallel to categories.

Returns a builder; set optional sort/paging and call ReleasesRequest::send to run it.

let results = client.releases().limit(20).send().await?;
println!("{} releases", results.count);

pub fn releases_dates(&self) -> ReleaseDatesRequest<'_>

Begin a request for the publication dates of all releases (the fred/releases/dates endpoint) — a release calendar across FRED, newest first by default.

Returns a builder; set optional sort/paging (and include_dates_with_no_data) and call ReleaseDatesRequest::send to run it.

let calendar = client.releases_dates().limit(20).send().await?;
println!("{} release dates", calendar.count);

pub async fn release(&self, release_id: ReleaseId) -> Result<Release>

Fetch a single release by id (the fred/release endpoint).

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub fn release_series(&self, release_id: ReleaseId) -> SeriesListRequest<'_>

Begin a request for the series in a release (the fred/release/series endpoint).

Returns a SeriesListRequest builder; set optional ordering/paging and call send to run it.

use ferric_fred::ReleaseId;
let results = client
    .release_series(ReleaseId::new(53))
    .limit(5)
    .send()
    .await?;
println!("{} series", results.count);

pub async fn release_sources( &self, release_id: ReleaseId, ) -> Result<Vec<Source>>

Fetch the sources for a release (the fred/release/sources endpoint) — the reverse of source_releases. FRED returns the full list unpaginated, so this yields a plain Vec<Source>.

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub fn release_dates(&self, release_id: ReleaseId) -> ReleaseDatesRequest<'_>

Begin a request for the publication dates of one release (the fred/release/dates endpoint) — that release’s calendar, oldest first by default.

Returns a ReleaseDatesRequest builder; set optional sort/paging (and include_dates_with_no_data) and call send to run it.

use ferric_fred::ReleaseId;
let dates = client.release_dates(ReleaseId::new(82)).limit(10).send().await?;
println!("{} release dates", dates.count);

pub fn release_tables(&self, release_id: ReleaseId) -> ReleaseTablesRequest<'_>

Begin a request for a release’s table tree (the fred/release/tables endpoint) — the nested layout (sections, tables, and series rows) a release uses to present its series.

Returns a builder; optionally scope to a subtree with element, then call ReleaseTablesRequest::send to run it.

use ferric_fred::ReleaseId;
let table = client.release_tables(ReleaseId::new(10)).send().await?;
println!("{} root elements", table.roots.len());

pub fn release_tags(&self, release_id: ReleaseId) -> TagsRequest<'_>

Begin a request for the tags used by the series in a release (the fred/release/tags endpoint) — the tag facets available when browsing a release.

Returns a TagsRequest builder; set optional tag-filter text/sort/ paging and call send to run it.

use ferric_fred::ReleaseId;
let results = client.release_tags(ReleaseId::new(53)).limit(10).send().await?;
println!("{} tags", results.count);

pub fn release_related_tags<I, S>( &self, release_id: ReleaseId, tag_names: I, ) -> TagsRequest<'_>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Begin a request for the tags that co-occur, within a release, with a seed set of tags (the fred/release/related_tags endpoint).

Accepts any iterable of seed tag names (joined with ; for FRED). Returns a TagsRequest builder; set optional tag-filter text/sort/ paging and call send to run it.

use ferric_fred::ReleaseId;
let results = client.release_related_tags(ReleaseId::new(53), ["gdp"]).send().await?;
println!("{} related tags", results.count);

pub fn tags(&self) -> TagsRequest<'_>

Begin a request to browse or search FRED’s tag vocabulary (the fred/tags endpoint).

Returns a builder; set optional search text/sort/paging and call TagsRequest::send to run it.

let results = client.tags().search_text("gdp").limit(10).send().await?;
println!("{} tags", results.count);

pub fn related_tags<I, S>(&self, tag_names: I) -> TagsRequest<'_>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Begin a request for the tags that co-occur with a seed set of tags (the fred/related_tags endpoint) — refine a faceted search by discovering adjacent tags.

Accepts any iterable of tag names (they are joined with ; for FRED). Returns a TagsRequest builder; set optional search text/sort/paging and call send to run it.

let results = client.related_tags(["gdp"]).limit(10).send().await?;
println!("{} tags related to gdp", results.count);

pub fn tags_series<I, S>(&self, tag_names: I) -> SeriesListRequest<'_>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Begin a request for the series carrying all of the given tags (the fred/tags/series endpoint) — faceted discovery.

Accepts any iterable of tag names (they are joined with ; for FRED). Returns a SeriesListRequest builder; set optional ordering/paging and call send to run it.

let results = client.tags_series(["gdp", "quarterly"]).limit(5).send().await?;
println!("{} series", results.count);

pub async fn series_tags(&self, series_id: &SeriesId) -> Result<TagsResults>

Fetch the tags attached to a series (the fred/series/tags endpoint) — the reverse of tags_series.

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub fn series_updates(&self) -> SeriesUpdatesRequest<'_>

Begin a request for the most recently updated series (the fred/series/updates endpoint) — a “what changed” feed, ordered by last-updated time.

Returns a builder; set an optional class filter/paging and call SeriesUpdatesRequest::send to run it.

let results = client.series_updates().limit(20).send().await?;
println!("{} recently updated", results.count);

pub fn series_vintagedates( &self, series_id: &SeriesId, ) -> VintageDatesRequest<'_>

Begin a request for a series’ vintage dates (the fred/series/vintagedates endpoint) — the dates on which the series was revised or newly released.

Returns a builder; set optional sort/paging and call VintageDatesRequest::send to run it.

use ferric_fred::SeriesId;
let dates = client
    .series_vintagedates(&SeriesId::new("GNPCA"))
    .limit(10)
    .send()
    .await?;
println!("{} vintage dates", dates.count);

pub async fn series_categories( &self, series_id: &SeriesId, ) -> Result<Vec<Category>>

Fetch the categories a series belongs to (the fred/series/categories endpoint) — the reverse of category_series.

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub async fn series_release(&self, series_id: &SeriesId) -> Result<Release>

Fetch the release a series belongs to (the fred/series/release endpoint) — the reverse of release_series.

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub fn sources(&self) -> SourcesRequest<'_>

Begin a request listing all FRED data sources (the fred/sources endpoint) — the organizations that produce releases.

Returns a builder; set optional sort/paging and call SourcesRequest::send to run it.

let results = client.sources().limit(20).send().await?;
println!("{} sources", results.count);

pub async fn source(&self, source_id: SourceId) -> Result<Source>

Fetch a single source by id (the fred/source endpoint).

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub fn source_releases(&self, source_id: SourceId) -> ReleasesRequest<'_>

Begin a request for the releases produced by a source (the fred/source/releases endpoint).

Returns a ReleasesRequest builder; set optional sort/paging and call send to run it.

use ferric_fred::SourceId;
let results = client.source_releases(SourceId::new(18)).limit(5).send().await?;
println!("{} releases", results.count);

pub async fn regional_data( &self, series_group: &SeriesGroupId, region_type: RegionType, date: NaiveDate, units: impl Into<String>, frequency: Frequency, season: SeasonalAdjustment, ) -> Result<RegionalData>

Fetch a region cross-section for a series group (the GeoFRED geofred/regional/data endpoint) — the value in every region of region_type on date, for the given units label, frequency, and season.

FRED requires all of these parameters (a live probe rejects any omission — ADR-0025), so this is a direct call rather than a builder. units is a free-form measurement label FRED echoes into the result title (e.g. "Dollars"), not a transformation code.

use ferric_fred::{Frequency, RegionType, SeasonalAdjustment, SeriesGroupId};
let date = chrono::NaiveDate::from_ymd_opt(2013, 1, 1).unwrap();
let data = client
    .regional_data(
        &SeriesGroupId::new("882"),
        RegionType::State,
        date,
        "Dollars",
        Frequency::Annual,
        SeasonalAdjustment::NotSeasonallyAdjusted,
    )
    .await?;
println!("{}", data.meta.title);

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub fn series_data(&self, series_id: &SeriesId) -> SeriesDataRequest<'_>

Begin a request for one regional series’ values across regions (the GeoFRED geofred/series/data endpoint).

Returns a builder; set an optional date or start_date and call send. With neither set, FRED returns the most recent date.

use ferric_fred::SeriesId;
let data = client
    .series_data(&SeriesId::new("SMU56000000500000001"))
    .send()
    .await?;
println!("{} dates", data.meta.data.len());

pub async fn series_group(&self, series_id: &SeriesId) -> Result<SeriesGroup>

Fetch the series-group metadata for a regional series (the GeoFRED geofred/series/group endpoint) — pass a regional series_id and get back the group it belongs to (title, region type, date span).

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

pub async fn shape_file(&self, shape: ShapeType) -> Result<ShapeFile>

Fetch the region boundary polygons for a shape type (the GeoFRED geofred/shapes/file endpoint) — a GeoJSON ShapeFile this crate transports without interpreting (ADR-0025).

Errors

Returns an error if the request fails to send, FRED returns a non-success status, or the response body cannot be deserialized.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.