fred-client

English | 한국어

Read economic statistics from the Federal Reserve Bank of St. Louis FRED, ALFRED, and GeoFRED services.

GDP and GNP, prices, employment and unemployment, interest rates, housing, industrial activity, financial markets, money, bank credit, federal finances, household income and saving, exchange rates, and bilateral trade are all covered. Read common indicators by name, such as fred.growth.gdp(), and use a series ID for everything else in FRED.

1. Install

pip install fred-client

fred-client requires a free FRED API key. Sign in to a FRED account and request or view keys on the official FRED API Keys page.

Option 1 — pass it directly (for a quick one-off use)

from fred_client import FRED

fred = FRED(api_key="your-api-key")

Option 2 — save it in a file (recommended, so you only enter it once)

Create ~/.config/fred-client/credentials.json with:

{
  "FRED_API_KEY": "your-api-key"
}

After that, FRED() finds the saved key automatically.

If you prefer an environment variable, use export FRED_API_KEY="your-api-key" on macOS and Linux, or setx FRED_API_KEY "your-api-key" in Windows PowerShell.

2. Quickstart

from fred_client import FRED

fred = FRED()                                                  # finds the saved key
gdp = fred.growth.gdp(observation_start="2020-01-01")          # GDP since 2020
recent = fred.labor.unemployment(limit=12, sort_order="desc")  # 12 latest values

Results are lists of dictionaries, so pandas or Polars can turn them into a DataFrame directly. Neither library is required by fred-client.

# pandas
import pandas as pd
pd.DataFrame(gdp)

# polars
import polars as pl
pl.DataFrame(gdp)

3. Common indicators (96)

Read these through grouped accessors such as fred.growth.gdp() without memorizing series IDs. Editors autocomplete the available groups and indicators.

gdp = fred.growth.gdp()
recent_unemployment = fred.labor.unemployment(limit=12, sort_order="desc")
inflation = fred.prices.consumer_prices(units="pc1")

• With no arguments, an indicator returns its complete available history in ascending date order.
• For recent values, use limit=12, sort_order="desc".
• Date bounds, frequency, and value transformations use the same options as series.observations().

In the tree below, a trailing / marks a group and every other line is an indicator. For example, m2_velocity inside money/ is fred.money.m2_velocity().

fred
├── growth/                                 # Output, income, and national accounts
│   ├── gdp                                 # GDP: Gross domestic product
│   ├── gnp                                 # GNP: Gross national product
│   ├── gdi                                 # GDI: Gross domestic income
│   ├── current_account_balance             # NETFI: Net foreign investment
│   ├── exports                             # EXPGS: Exports of goods and services
│   ├── imports                             # IMPGS: Imports of goods and services
│   ├── corporate_profits_after_tax         # CP: Corporate profits after tax
│   └── corporate_dividends                 # DIVIDEND: Corporate dividends
├── prices/                                 # Consumer and producer prices
│   ├── consumer_prices                     # CPIAUCSL: Consumer price index
│   └── producer_prices                     # PPIACO: Producer price index
├── labor/                                  # Employment, unemployment, population, and earnings
│   ├── unemployment                        # UNRATE: Unemployment rate
│   ├── long_term_unemployment              # UEMP27OV: Unemployed for 27 weeks or longer
│   ├── median_unemployment_duration        # UEMPMED: Median unemployment duration
│   ├── employment                          # CE16OV: Civilian employment
│   ├── employment_population_ratio         # EMRATIO: Employment-population ratio
│   ├── total_population                    # POP: Total population
│   ├── manufacturing_hourly_earnings       # AHEMAN: Manufacturing hourly earnings
│   ├── manufacturing_weekly_hours          # AWHMAN: Manufacturing weekly hours
│   └── manufacturing_overtime_hours        # AWOTMAN: Manufacturing overtime hours
├── rates/                                  # Policy, Treasury, yield-curve, and mortgage rates
│   ├── federal_funds                       # FEDFUNDS: Federal funds rate
│   ├── discount_window_primary_credit      # DPCREDIT: Primary credit rate
│   ├── treasury_bill_3_month               # TB3MS: 3-month Treasury bill rate
│   ├── treasury_10_year                    # DGS10: 10-year Treasury rate
│   ├── yield_curve_10y_2y                  # T10Y2Y: 10-year minus 2-year spread
│   └── mortgage_30_year                    # MORTGAGE30US: 30-year mortgage rate
├── housing/                                # Residential construction and sales
│   ├── permits                             # PERMIT: New private housing permits
│   └── new_home_sales                      # HSN1F: New one-family home sales
├── industry/                               # Production, inventories, construction, and sales
│   ├── durable_goods_orders                # DGORDER: Durable goods orders
│   ├── capacity_utilization                # TCU: Capacity utilization
│   ├── construction_spending               # TTLCONS: Total construction spending
│   ├── business_inventories                # BUSINV: Total business inventories
│   ├── light_vehicle_sales                 # ALTSALES: Light vehicle sales
│   ├── semiconductor_production            # IPG3344S: Semiconductor and electronic component production
│   └── semiconductor_capacity_utilization  # CAPUTLG3344S: Semiconductor capacity utilization
├── markets/                                # Volatility, financial stress, and commodities
│   ├── volatility                          # VIXCLS: CBOE volatility index
│   ├── financial_stress                    # STLFSI: St. Louis Fed financial stress index
│   └── wti                                 # WCOILWTICO: WTI spot price at Cushing, Oklahoma
├── money/                                  # Money supply, velocity, and Federal Reserve holdings
│   ├── treasury_securities                 # TREAST: Treasury securities held by the Fed
│   ├── mortgage_backed_securities          # WSHOMCB: Mortgage-backed securities held by the Fed
│   ├── federal_reserve_assets              # WALCL: Federal Reserve total assets
│   ├── m1                                  # M1SL: M1 money stock
│   ├── m2                                  # M2SL: M2 money stock
│   ├── m1_velocity                         # M1V: Velocity of M1
│   └── m2_velocity                         # M2V: Velocity of M2
├── banking/                                # Bank balance sheets, lending, and credit
│   ├── total_assets                        # TLAACBW027SBOG: Commercial bank assets
│   ├── bank_credit                         # TOTBKCR: Bank credit
│   ├── securitized_consumer_credit         # TOTALSEC: Securitized consumer credit
│   ├── total_consumer_credit               # TOTALSL: Consumer credit
│   ├── securities_in_bank_credit           # INVEST: Securities in bank credit
│   ├── treasury_and_agency_securities      # USGSEC: Treasury and agency securities
│   ├── consumer_loans                      # CONSUMER: Consumer loans
│   ├── commercial_and_industrial_loans     # BUSLOANS: Commercial and industrial loans
│   ├── consumer_loan_delinquencies         # DALLCACBEP: Consumer loan delinquency rate
│   └── commercial_paper_outstanding        # COMPOUT: Commercial paper outstanding
├── fiscal/                                 # Federal debt, receipts, outlays, and saving
│   ├── total_public_debt                   # GFDEBTN: Federal debt
│   ├── interest_outlays                    # FYOINT: Federal interest outlays
│   ├── net_outlays                         # FYONET: Federal net outlays
│   ├── annual_receipts                     # FYFR: Federal receipts
│   ├── annual_surplus_or_deficit           # FYFSD: Federal surplus or deficit
│   ├── defense_investment                  # DGI: Defense gross investment
│   ├── current_receipts                    # FGRECPT: Federal current receipts
│   └── net_government_saving               # TGDEF: Net government saving
├── households/                             # Household finances, income, saving, and sentiment
│   ├── debt_service_ratio                  # CDSP: Household debt service ratio
│   ├── debt                                # CMDEBT: Household debt
│   ├── consumer_sentiment                  # UMCSENT: Consumer sentiment
│   ├── personal_income                     # PI: Personal income
│   ├── personal_saving                     # PSAVE: Personal saving
│   └── personal_saving_rate                # PSAVERT: Personal saving rate
├── exchange_rates/                         # Major bilateral exchange rates
│   ├── usd_per_british_pound               # DEXUSUK: U.S. dollars per British pound
│   ├── usd_per_euro                        # DEXUSEU: U.S. dollars per euro
│   ├── japanese_yen_per_usd                # DEXJPUS: Japanese yen per U.S. dollar
│   ├── mexican_pesos_per_usd               # DEXMXUS: Mexican pesos per U.S. dollar
│   ├── canadian_dollars_per_usd            # DEXCAUS: Canadian dollars per U.S. dollar
│   ├── chinese_yuan_per_usd                # DEXCHUS: Chinese yuan per U.S. dollar
│   └── korean_won_per_usd                  # DEXKOUS: Korean won per U.S. dollar
└── trade/                                  # Bilateral and balance-of-payments trade
    ├── imports_from_china                  # IMPCH: Imports from China
    ├── imports_from_japan                  # IMPJP: Imports from Japan
    ├── imports_from_mexico                 # IMPMX: Imports from Mexico
    ├── imports_from_canada                 # IMPCA: Imports from Canada
    ├── imports_from_germany                # IMPGE: Imports from Germany
    ├── imports_from_korea                  # IMPKR: Imports from Korea
    ├── imports_from_united_kingdom         # IMPUK: Imports from the United Kingdom
    ├── exports_to_china                    # EXPCH: Exports to China
    ├── exports_to_japan                    # EXPJP: Exports to Japan
    ├── exports_to_mexico                   # EXPMX: Exports to Mexico
    ├── exports_to_canada                   # EXPCA: Exports to Canada
    ├── exports_to_germany                  # EXPGE: Exports to Germany
    ├── exports_to_korea                    # EXPKR: Exports to Korea
    ├── exports_to_united_kingdom           # EXPUK: Exports to the United Kingdom
    ├── goods_exports                       # BOPGEXP: Goods exports
    ├── goods_imports                       # BOPGIMP: Goods imports
    ├── goods_balance                       # BOPGTB: Goods trade balance
    ├── services_exports                    # BOPSEXP: Services exports
    ├── services_imports                    # BOPSIMP: Services imports
    ├── services_balance                    # BOPSTB: Services trade balance
    └── goods_and_services_balance          # BOPGSTB: Goods and services balance

4. Everything else in FRED

For a series outside the 96 common indicators, search for its series ID and then fetch it.

# 1) Search
matches = fred.series.search("real gdp per capita", limit=10)

# 2) Inspect the chosen series
info = fred.series.get("A939RX0Q048SBEA")

# 3) Fetch a date range
rows = fred.series.observations(
    "A939RX0Q048SBEA",
    observation_start="2020-01-01",
    observation_end="2025-12-31",
)

series.get() returns one series description; searches and observations return list[dict].

Historical vintages (ALFRED)

To compare values as they were published on earlier dates, pass vintage dates:

rows = fred.series.observations(
    "GDP",
    output_type=2,
    vintage_dates=["2020-01-01", "2025-01-01"],
)

Complete release histories

release = fred.release.observations(52)

The client follows every page and merges split histories into one result.

5. Command line

Installing the package also installs the fred command.

fred list                                                       # all accessors
fred list growth                                                # the growth group
fred fetch growth gdp                                           # fred.growth.gdp()
fred fetch labor unemployment --limit 12 --sort-order desc      # 12 latest unemployment values
fred fetch GDP                                                  # any series ID
fred metadata GDP                                               # title, units, and frequency
fred search "unemployment rate" --limit 10                      # find series IDs
fred fetch GDP --json                                           # raw rows as JSON, not a table
fred --version

list prints a readable index; data commands print aligned output, or the raw response as JSON with --json (a long table shows its first and last 10 rows). See fred <command> --help for all options. list and --version work offline without an API key. Series IDs are case-insensitive, so fred fetch GDP and fred fetch gdp are equivalent.

6. Use with AI coding agents

This repository is also a Claude Code and Codex plugin marketplace. The list, fetch, metadata, and search skills call the matching fred commands. Install the package and configure the API key first. list does not need a key.

6.1 Claude Code

In the Claude Code chat, add the marketplace and install:

/plugin marketplace add seokhoonj/fred-client
/plugin install fred@fred-client

Ask naturally (“find the FRED code for unemployment,” “show GDP since 2020”) or invoke a skill: /fred:search unemployment rate, /fred:fetch GDP --observation-start 2020-01-01.

6.2 Codex

In your terminal, add the marketplace and install:

codex plugin marketplace add seokhoonj/fred-client
codex plugin add fred@fred-client

The four skills respond automatically to matching economic-data requests.

To use them without the plugin, symlink the skill directories:

for skill in list fetch metadata search; do
  ln -s "$PWD/plugins/fred/skills/$skill" ~/.claude/skills/$skill
  ln -s "$PWD/plugins/fred/skills/$skill" ~/.codex/skills/$skill
done

Claude Code discovers the links immediately; restart Codex to load them.

7. Notes

• Observation values remain strings exactly as FRED sends them. A missing value is ".".
• Calling a common indicator without arguments fetches its full history. For recent values, combine limit with sort_order="desc".
• fred.maps remains an alias of fred.geo for compatibility.
• The STLFSI financial-stress series is discontinued historical data and no longer receives new observations.
• The first 91 common indicators came from Wikipedia's partial FRED indicator list; three Korea trade and exchange-rate series and two semiconductor series (production and capacity utilization) extend it. The group names are fred-client's navigation aid, not official FRED categories.

8. Errors

Every operational error derives from FREDError.

from fred_client import FRED, FREDError

try:
    observations = FRED().series.observations("GDP")
except FREDError as error:
    print(error)

Error messages and representations never include the API key.

9. License

MIT © Seokhoon Joo