FedFred API Overview#

FedFred provides a modular, structured client interface for interacting with the FRED® API, supporting both synchronous and asynchronous access.

This page summarizes the main client classes, their features, and how they relate to FRED data categories.

—

Client Architecture#

Expand Client Class Hierarchy

Each class is accessed as an attribute:

  • FredAPI.Async → async core

  • FredAPI.Maps → sync Maps API

  • FredAPI.Async.Maps → async Maps API

—

Client Capabilities#

Category Access Retrieve parent/child metadata trees for all FRED categories. Useful for hierarchy navigation and dataset discovery.
Series Metadata + Observations Fetch time series data and associated metadata (titles, units, frequency, vintages).
Releases Access scheduled FRED economic data releases including descriptions, dates, and series.
Tags + Search Use keyword/tag search to discover new indicators programmatically.
Vintage Series Support Retrieve historical vintages to build forecasting models or study revisions.
Regional Data (GeoFRED) Use MapsAPI and AsyncMapsAPI to access state/county-level economic indicators.

—

Enhanced API Features#

Local Caching FIFO cache stores recent results in memory. Configurable via cache_mode and cache_size.
Retry Logic Failed requests automatically retried with exponential backoff (powered by tenacity).
Rate Limiting Enforces FRED’s 120 requests/minute rule with a timestamp deque.
DataFrame Outputs Returns data as:

  • pandas (default)

  • polars

  • dask

  • geopandas

  • polars_st / dask_geopandas

Fully typed and datetime-aware.

Structured Models API results parsed into rich typed objects like:

—