FRED Federal Reserve Economic Data Scraper

Extract 800,000+ economic time series from the Federal Reserve's FRED database. Fetch macroeconomic indicators like GDP, unemployment, inflation (CPI), treasury yields, housing starts, and much more. Perfect for financial dashboards, economic research, trading signal development, and fintech applications.

What This Actor Does

This Actor provides a complete interface to the FRED (Federal Reserve Economic Data) API, maintained by the Federal Reserve Bank of St. Louis. It supports four operating modes:

1. Fetch Time Series Observations — Retrieve historical economic data for one or more series IDs (e.g., track the 10-year Treasury yield, unemployment rate, or S&P 500 index across decades)
2. Search Series by Text — Find series IDs by keyword search (e.g., search for "yield curve" or "housing starts")
3. List Category Series — Enumerate all series within a FRED category (e.g., "Money, Banking, & Finance")
4. Fetch Release Schedules — Get FRED data release calendars and publication metadata

Key Features

• 800,000+ series — Complete FRED database access
• Flexible filtering — Date ranges, resampling frequencies (daily → annual), unit transformations (raw, % change, log)
• Pagination support — Unlimited results (up to API limits)
• Batch processing — Efficient extraction for large datasets
• API key protected — Your credentials stored securely
• Error handling — Graceful fallback for missing or inaccessible data
• Zero login required — Free API key registration takes 30 seconds

Popular Series IDs (Examples)

Series ID	Description	Units
GDP	Real Gross Domestic Product	Billions of USD (annual)
UNRATE	Civilian Unemployment Rate	%
CPIAUCSL	Consumer Price Index (CPI-U)	Index, 1982-84 = 100
FEDFUNDS	Effective Federal Funds Rate	%
DFF	Federal Funds Effective Rate (daily)	%
T10Y2Y	10-Year Treasury Constant Maturity minus 2-Year	% (yield curve steepness)
DGS10	10-Year Treasury Constant Maturity Rate	%
MORTGAGE30US	30-Year Fixed Rate Mortgage Average	%
PAYEMS	Total Nonfarm Payroll	Thousands
HOUST	Housing Starts	Thousands (annual rate)
SP500	S&P 500 Index	Index level
VIXCLS	CBOE Volatility Index (VIX)	Index points
UMCSENT	University of Michigan Consumer Sentiment Index	Index
INDPRO	Industrial Production Index	Index, 2017 = 100
RSAFS	Retail Sales (excluding automobiles)	Billions USD, annual rate
ICSA	Initial Claims (weekly)	Thousands

Getting Started

Step 1: Create a Free FRED API Key (30 seconds)

1. Visit https://fredaccount.stlouisfed.org/apikeys
2. Sign up (or log in)
3. Create an API key
4. Copy your 32-character key

Step 2: Run the Actor

1. Paste your API key into the FRED API Key input field
2. Choose a Mode:
   • series_observations (default) — Fetch time-series data
   • series_search — Search by text
   • category_series — List all series in a category
   • releases — Get data release schedules
3. Configure mode-specific inputs (see below)
4. Click Start

Step 3: Download Results

Results appear as JSON in the Dataset tab. Export as CSV/JSON via the Apify UI.

Tutorials

Tutorial 1: Track the 10-Year Treasury Yield (DGS10) for 2024

Goal: Fetch daily Treasury yield data for 2024 to visualize the yield curve movements.

Input configuration:

• Mode: series_observations
• Series IDs: DGS10
• Observation Start: 2024-01-01
• Observation End: 2024-12-31
• Frequency: d (daily)
• Units: lin (raw interest rate %)
• Max Results: 1000 (more than enough for ~252 trading days)

Expected output:

[
  {
    "seriesId": "DGS10",
    "seriesTitle": "10-Year Treasury Constant Maturity Rate",
    "date": "2024-01-02",
    "value": 3.85,
    "units": "%",
    "frequency": "daily",
    "lastUpdated": "2025-04-20T17:00:00",
    "popularity": 100
  },
  {
    "seriesId": "DGS10",
    "seriesTitle": "10-Year Treasury Constant Maturity Rate",
    "date": "2024-01-03",
    "value": 3.82,
    "units": "%",
    "frequency": "daily",
    "lastUpdated": "2025-04-20T17:00:00",
    "popularity": 100
  },
  ...
]

Use case: Feed this data into a charting library to visualize Treasury yield movements, or calculate volatility metrics for bond trading strategies.

---

Tutorial 2: Search for Unemployment-Related Series

Goal: Find all FRED series related to unemployment to build a comprehensive labor market dashboard.

Input configuration:

• Mode: series_search
• Search Text: unemployment rate
• Max Results: 100

Expected output:

[
  {
    "seriesId": "UNRATE",
    "title": "Civilian Unemployment Rate",
    "frequency": "Monthly",
    "units": "%",
    "observationStart": "1948-01-01",
    "observationEnd": "2025-04-01",
    "popularity": 100,
    "notes": "The unemployment rate represents the number of unemployed persons..."
  },
  {
    "seriesId": "UNRATESA",
    "title": "Civilian Unemployment Rate (Seasonally Adjusted)",
    "frequency": "Monthly",
    "units": "%",
    "observationStart": "1948-01-01",
    "observationEnd": "2025-04-01",
    "popularity": 95
  },
  ...
]

Use case: Identify all related series, then use their Series IDs to fetch historical observations in a follow-up run.

---

Tutorial 3: Fetch Inflation Data with Unit Transformations

Goal: Extract CPI data and calculate year-over-year percent change to show inflation trends.

Input configuration:

• Mode: series_observations
• Series IDs: CPIAUCSL
• Observation Start: 2020-01-01
• Frequency: m (monthly — the base frequency for CPI)
• Units: pch (percent change — shows month-over-month % change)
• Max Results: 100

Expected output:

[
  {
    "seriesId": "CPIAUCSL",
    "seriesTitle": "Consumer Price Index for All Urban Consumers: All items",
    "date": "2025-04-01",
    "value": 0.41,
    "units": "%",
    "appliedUnits": "pch",
    "frequency": "Monthly",
    "lastUpdated": "2025-05-09T08:00:00",
    "popularity": 95
  },
  ...
]

Note: The appliedUnits field shows "pch" because we requested percent change. The value is now the monthly percent change instead of the index level.

---

Input Parameters

Mode: series_observations (Default)

Fetch historical observations (time series data) for one or more FRED series.

Parameter	Type	Default	Description
apiKey	string (secret)	—	Your FRED API key (32 chars, required)
mode	enum	series_observations	Set to series_observations
seriesIds	string	GDP	Comma-separated series IDs (e.g., "GDP,UNRATE,CPIAUCSL")
observationStart	string (YYYY-MM-DD)	—	Earliest date (blank = oldest available)
observationEnd	string (YYYY-MM-DD)	—	Latest date (blank = most recent)
frequency	enum	—	Resample frequency: "" (native), "d" (daily), "w" (weekly), "bw" (biweekly), "m" (monthly), "q" (quarterly), "sa" (semi-annual), "a" (annual)
aggregationMethod	enum	avg	When resampling: "avg" (average), "sum" (sum), "eop" (end of period)
units	enum	lin	Transform units: "lin" (raw), "chg" (change), "pch" (% change), "pca" (compound annual %), "log" (natural log)
sortOrder	enum	desc	Sort by date: "asc" (oldest first), "desc" (newest first)
maxResults	integer	1000	Maximum observations to fetch (0 = unlimited, up to 100,000)

Output fields:

• seriesId, seriesTitle, frequency, frequencyShort, units, unitsShort, seasonalAdjustment, seasonalAdjustmentShort
• lastUpdated, popularity, notes, observationStart, observationEnd
• date (observation date), value (parsed as number, null if missing)
• realtimeStart, realtimeEnd (FRED revision metadata)
• appliedUnits, appliedFrequency (the transformations applied)

---

Mode: series_search

Search for series by keyword.

Parameter	Type	Default	Description
apiKey	string (secret)	—	Your FRED API key (required)
mode	enum	—	Set to series_search
searchText	string	—	Free-text search query (required if mode = series_search). Examples: "unemployment rate", "inflation", "housing"
maxResults	integer	1000	Maximum series to return (0 = unlimited, up to 1,000)

Output fields:

• seriesId, title, notes, frequency, frequencyShort, units, unitsShort, seasonalAdjustment
• observationStart, observationEnd, lastUpdated, popularity, groupPopularity
• realtimeStart, realtimeEnd

---

Mode: category_series

List all series in a FRED category.

Parameter	Type	Default	Description
apiKey	string (secret)	—	Your FRED API key (required)
mode	enum	—	Set to category_series
categoryId	integer	32991	FRED category ID. Examples: 32991 (Money, Banking, Finance), 9 (Population), 106 (Real estate)
maxResults	integer	1000	Maximum series to return (0 = unlimited)

Output fields: Same as series_search.

---

Mode: releases

Fetch FRED data release schedules.

Parameter	Type	Default	Description
apiKey	string (secret)	—	Your FRED API key (required)
mode	enum	—	Set to releases
maxResults	integer	1000	Maximum releases to return (0 = unlimited)

Output fields:

• releaseId, name, pressRelease (boolean), link, notes
• realtimeStart, realtimeEnd

---

Pricing

This Actor uses the free FRED API (no usage limits). You pay only for Apify compute time.

• Compute cost: ~$0.0001-0.001 per run (depends on data volume and API latency)
• Typical cost per batch: $0.01-0.10 for 100-1000 observations
• Bulk runs (1000+ observations): ~$0.10-0.50 per run

The FRED API itself is completely free — no subscriptions, no per-request charges.

---

Output Examples

Example 1: Single Series Observation (series_observations mode)

{
  "seriesId": "GDP",
  "seriesTitle": "Real Gross Domestic Product",
  "frequency": "Quarterly",
  "frequencyShort": "q",
  "units": "Billions of Chained 2012 US Dollars",
  "unitsShort": "Bil. of Chn. 2012 $",
  "seasonalAdjustment": "Seasonally Adjusted",
  "seasonalAdjustmentShort": "SA",
  "lastUpdated": "2025-04-30T07:58:00",
  "popularity": 100,
  "notes": "Real GDP is the inflation adjusted value of the goods and services produced by labor and property located in the United States.",
  "observationStart": "1947-01-01",
  "observationEnd": "2025-01-01",
  "date": "2024-10-01",
  "value": 28481.0,
  "realtimeStart": "2024-10-01",
  "realtimeEnd": "2024-10-01",
  "appliedUnits": "lin",
  "appliedFrequency": null
}

Example 2: Search Results (series_search mode)

{
  "seriesId": "PAYEMS",
  "title": "Total Nonfarm Payroll",
  "notes": "The number of employees on the payroll of non-farm business establishments. Excludes proprietors and self-employed. Seasonally adjusted.",
  "frequency": "Monthly",
  "frequencyShort": "m",
  "units": "Thousands of Persons",
  "unitsShort": "Tho. of Persons",
  "seasonalAdjustment": "Seasonally Adjusted",
  "seasonalAdjustmentShort": "SA",
  "observationStart": "1939-01-01",
  "observationEnd": "2025-04-01",
  "lastUpdated": "2025-05-02T08:00:00",
  "popularity": 98,
  "groupPopularity": 95,
  "realtimeStart": "2025-05-02",
  "realtimeEnd": "2025-05-02"
}

Example 3: Data Release (releases mode)

{
  "releaseId": 13,
  "name": "Real Estate Transactions by State",
  "pressRelease": false,
  "link": "https://www.redfin.com/news/data-center/",
  "notes": "Includes transaction counts and average prices for residential real estate.",
  "realtimeStart": "2025-01-15",
  "realtimeEnd": "2025-05-02"
}

---

Troubleshooting

"API key format invalid" error

• Ensure your API key is exactly 32 alphanumeric characters
• Do not include quotes or spaces
• If you lost your key, regenerate one at https://fredaccount.stlouisfed.org/apikeys

"No records found" for a series search

• Try a simpler search term (e.g., "unemployment" instead of "civilian unemployment rate")
• Check FRED directly at https://fred.stlouisfed.org to verify the series exists
• Some series may be discontinued or have limited data

"Bad series ID" error

• Verify the series ID exists on https://fred.stlouisfed.org/series/
• Series IDs are case-sensitive but typically uppercase (e.g., "GDP", not "gdp")
• Use the search mode to discover available series IDs

Large data requests timeout

• Reduce the date range (e.g., fetch 5 years at a time instead of 30)
• Lower maxResults to test smaller batches first
• FRED API has a 100,000-observation limit per request

Performance / Cost Concerns

• Each series requires a separate API call to fetch metadata, then one or more calls for observations
• For bulk data, prefer using observation-level frequency (e.g., "m" for monthly) over daily if possible
• The Actor batches results efficiently and exits cleanly to minimize compute cost

---

API Reference

For detailed FRED API documentation, see https://fredaccount.stlouisfed.org/docs/

Common endpoints this Actor uses:

• GET /series/observations — Fetch time-series observations
• GET /series/search — Search series by text
• GET /category/series — List series in a category
• GET /releases — List data releases
• GET /series — Get series metadata

---

Related Actors

Looking for other economic or financial data sources?

• U.S. Economic Census Data — Census Bureau datasets
• Stock Market Data Scraper — Real-time and historical price data
• World Bank Open Data — Global economic indicators
• Yahoo Finance Scraper — Stock and commodity prices

---

Legal & Support

Disclaimer: This Actor fetches data from the FRED API, which is maintained by the Federal Reserve Bank of St. Louis. The data is public domain and free to use. Always verify FRED's terms of use at https://fred.stlouisfed.org.

Support: If you encounter issues:

1. Check the FRED API docs: https://fredaccount.stlouisfed.org/docs/
2. Verify your API key is valid
3. Test the API directly: curl "https://api.stlouisfed.org/fred/series?series_id=GDP&api_key=YOUR_KEY&file_type=json"
4. Open an issue on Apify Community or contact support

---

Built with ❤️ for economists, traders, and fintech developers.