ferric_fred/
lib.rs

1//! `ferric-fred` — a strongly-typed async Rust client for the [FRED] API
2//! (Federal Reserve Economic Data, from the Federal Reserve Bank of St. Louis).
3//!
4//! [FRED]: https://fred.stlouisfed.org/
5//!
6//! The client covers all of FRED's read endpoints — series, observations,
7//! search, categories, releases, sources, tags, and the release table tree —
8//! plus the GeoFRED / Maps API for regional data and its geographic shape files,
9//! behind ergonomic async builders, with newtype identifiers, typed enums for
10//! FRED's closed value sets, and a typed [`Error`] taxonomy that never panics on
11//! a network or parse failure. Paginated endpoints can be walked to exhaustion
12//! with [`Paginate::send_all`] or streamed lazily with [`Paginate::stream`]. See
13//! the design ADRs under `docs/adr/` for the decisions that shape the API.
14//!
15//! # Feature flags
16//!
17//! - `schemars` *(off by default)* — derive `schemars::JsonSchema` on the
18//!   public return types, so a consumer (the bundled MCP server, say) can
19//!   advertise the exact shape an endpoint returns. Additive; plain consumers
20//!   pay nothing. See [ADR-0023].
21//!
22//! [ADR-0023]: https://github.com/ojhermann-org/ferric-fred/blob/main/docs/adr/0023-mcp-output-schemas.md
23//!
24//! ```no_run
25//! # async fn run() -> ferric_fred::Result<()> {
26//! use ferric_fred::{Client, Paginate, SeriesId};
27//!
28//! let client = Client::from_env()?; // reads FRED_API_KEY
29//!
30//! // One series' observations:
31//! let observations = client.observations(&SeriesId::new("GNPCA")).send().await?;
32//! println!("{} observations", observations.len());
33//!
34//! // Search, paged to exhaustion (or `.stream()` for lazy iteration):
35//! let matches = client.search("unemployment rate").send_all().await?;
36//! println!("{} matching series", matches.len());
37//! # Ok(())
38//! # }
39//! ```
40
41mod aggregation_method;
42mod category;
43mod client;
44mod error;
45mod frequency;
46mod ids;
47mod observation;
48mod observations_request;
49mod order_by;
50mod paginate;
51mod region_type;
52mod regional_data;
53mod release;
54mod release_date;
55mod release_dates_request;
56mod release_table;
57mod release_tables_request;
58mod releases_request;
59mod search_type;
60mod seasonal_adjustment;
61mod series;
62mod series_data_request;
63mod series_group;
64mod series_list_request;
65mod series_search_request;
66mod series_updates_request;
67mod shape_file;
68mod shape_type;
69mod sort_order;
70mod source;
71mod sources_request;
72mod tag;
73mod tags_request;
74mod units;
75mod updates_filter;
76mod vintage_dates;
77mod vintage_dates_request;
78
79pub use aggregation_method::AggregationMethod;
80pub use category::Category;
81pub use client::Client;
82pub use error::Error;
83pub use frequency::Frequency;
84pub use ids::{CategoryId, ReleaseElementId, ReleaseId, SeriesGroupId, SeriesId, SourceId};
85pub use observation::Observation;
86pub use observations_request::ObservationsRequest;
87pub use order_by::OrderBy;
88pub use paginate::{Page, Paginate};
89pub use region_type::RegionType;
90pub use regional_data::{RegionalData, RegionalDataMeta, RegionalDataPoint};
91pub use release::{Release, ReleasesResults};
92pub use release_date::{ReleaseDate, ReleaseDatesResults};
93pub use release_dates_request::ReleaseDatesRequest;
94pub use release_table::{ReleaseTable, ReleaseTableElement};
95pub use release_tables_request::ReleaseTablesRequest;
96pub use releases_request::ReleasesRequest;
97pub use search_type::SearchType;
98pub use seasonal_adjustment::SeasonalAdjustment;
99pub use series::{Series, SeriesSearchResults};
100pub use series_data_request::SeriesDataRequest;
101pub use series_group::SeriesGroup;
102pub use series_list_request::SeriesListRequest;
103pub use series_search_request::SeriesSearchRequest;
104pub use series_updates_request::SeriesUpdatesRequest;
105pub use shape_file::{Feature, Geometry, ShapeFile};
106pub use shape_type::ShapeType;
107pub use sort_order::SortOrder;
108pub use source::{Source, SourcesResults};
109pub use sources_request::SourcesRequest;
110pub use tag::{Tag, TagsResults};
111pub use tags_request::TagsRequest;
112pub use units::Units;
113pub use updates_filter::UpdatesFilter;
114pub use vintage_dates::VintageDates;
115pub use vintage_dates_request::VintageDatesRequest;
116
117/// A `Result` whose error type is this crate's [`Error`].
118pub type Result<T> = std::result::Result<T, Error>;
ferric_fred/lib.rs

ferric_fred/
lib.rs
