Metadata-Version: 2.4
Name: fred-client
Version: 0.1.0
Summary: Read the FRED / ALFRED economic data API: series, observations, releases, categories, sources, tags, and GeoFRED maps.
Project-URL: Homepage, https://github.com/seokhoonj/fred-client
Project-URL: Repository, https://github.com/seokhoonj/fred-client
Project-URL: Issues, https://github.com/seokhoonj/fred-client/issues
Author-email: Seokhoon Joo <seokhoonj@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: alfred,economic data,federal reserve,fred,macro,st louis fed
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# fred-client

[![check](https://github.com/seokhoonj/fred-client/actions/workflows/check.yml/badge.svg)](https://github.com/seokhoonj/fred-client/actions/workflows/check.yml)
[![PyPI](https://img.shields.io/pypi/v/fred-client)](https://pypi.org/project/fred-client/)
[![Python](https://img.shields.io/pypi/pyversions/fred-client)](https://pypi.org/project/fred-client/)
[![License](https://img.shields.io/pypi/l/fred-client)](https://github.com/seokhoonj/fred-client/blob/main/LICENSE)

**English** | [한국어](https://github.com/seokhoonj/fred-client/blob/main/README.ko.md)

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

```sh
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](https://fredaccount.stlouisfed.org/apikeys) page.

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

```python
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:

```json
{
  "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

```python
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.

```python
# 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.

```python
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()`.

```text
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.

```python
# 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]`.

| Accessor | Data |
|---|---|
| `fred.series` | Search, metadata, observations, and revision history |
| `fred.category` | FRED categories and their series |
| `fred.release` | Releases, dates, included series, and bulk histories |
| `fred.source` | Data publishers and their releases |
| `fred.tag` | Tags and matching series |
| `fred.geo` | GeoFRED regional data and map shapes |

### Historical vintages (ALFRED)

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

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

### Complete release histories

```python
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.

```sh
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:

```text
/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:

```sh
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:

```sh
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](https://en.wikipedia.org/wiki/Federal_Reserve_Economic_Data#FRED_economic_indicators_(partial_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`.

| Error | Meaning |
|---|---|
| `FREDConfigError` | No usable API key or a malformed credentials file |
| `FREDAuthError` | FRED rejected the API key |
| `FREDRateLimitError` | FRED returned HTTP 429 |
| `FREDResponseError` | Another structured FRED error response |
| `FREDNetworkError` | Transport, HTTP-body, or JSON decoding failure |
| `FREDProtocolError` | Successful JSON violated the endpoint response contract |

```python
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
