FRED Economic Data Search

FRED Economic Data Search is an Apify actor that connects to the Federal Reserve Economic Data (FRED) API to search, retrieve, and download US economic time series data. With access to over 840,000 data series maintained by the Federal Reserve Bank of St. Louis, this actor delivers GDP figures, unemployment rates, inflation metrics, interest rates, housing data, and hundreds of thousands of other indicators in structured JSON format -- ready for analysis, dashboards, or automated pipelines.

---

Why use FRED Economic Data Search?

Accessing FRED data programmatically requires handling API authentication, pagination, missing value filtering, and response normalization. This actor eliminates that development overhead. You configure a query through a simple web form or JSON input, run the actor on Apify, and receive clean, structured data in seconds.

Running on Apify gives you scheduled recurring data pulls, cloud-based execution with no infrastructure to maintain, built-in integrations with Google Sheets and Slack, and dataset export in JSON, CSV, or Excel. The actor is purpose-built for economists, financial analysts, data scientists, journalists, and researchers who need reliable, automated access to US economic statistics.

---

Key features

• 840,000+ economic time series searchable by keyword, ranked by popularity
• Three operating modes -- search for series discovery, observations for time series data, series for metadata lookup
• Date range filtering with configurable start and end dates on observation data
• Frequency aggregation to convert data to daily, weekly, biweekly, monthly, quarterly, semi-annual, or annual intervals
• Automatic missing data filtering that removes FRED's "." placeholder values from results
• Pagination support with configurable results up to 1,000 series per search
• Rich metadata including units, seasonal adjustment, popularity scores, and descriptive notes
• Dry-run mode that outputs setup instructions when no API key is provided
• Clean JSON output exportable to CSV, Excel, Google Sheets, or consumable via API

---

How to use FRED Economic Data Search

1. Get a free FRED API key. Visit https://fred.stlouisfed.org/docs/api/api_key.html, create a free account, and request an API key from your account settings.
2. Open the actor on the Apify Console or call it via the API.
3. Choose your mode. Select search to discover data series by keyword, observations to download actual data values, or series to retrieve metadata about known series IDs.
4. Configure your query. For search mode, enter keywords like "GDP" or "unemployment". For observations or series mode, provide FRED series IDs such as GDP, UNRATE, CPIAUCSL, or FEDFUNDS.
5. Set optional filters. Narrow observation data with start/end dates and choose a frequency aggregation level.
6. Run the actor and download results from the dataset in JSON, CSV, or Excel format.

---

Input parameters

Parameter	Type	Required	Default	Description
apiKey	String	Yes	--	Free FRED API key from fred.stlouisfed.org.
mode	String	No	search	Operating mode: search, observations, or series.
searchText	String	Conditional	--	Keywords to search for economic series. Required when mode is search.
seriesIds	String[]	Conditional	--	One or more FRED series IDs. Required for observations and series modes.
startDate	String	No	--	Start date for observations in YYYY-MM-DD format.
endDate	String	No	--	End date for observations in YYYY-MM-DD format.
frequency	String	No	--	Aggregate to: d (daily), w (weekly), bw (biweekly), m (monthly), q (quarterly), sa (semi-annual), a (annual).
maxResults	Integer	No	50	Maximum series to return in search mode (1--1,000).

Input example (search mode)

{
    "apiKey": "your_fred_api_key_here",
    "mode": "search",
    "searchText": "GDP",
    "maxResults": 10
}

Input example (observations mode)

{
    "apiKey": "your_fred_api_key_here",
    "mode": "observations",
    "seriesIds": ["UNRATE", "CPIAUCSL"],
    "startDate": "2023-01-01",
    "endDate": "2023-12-31",
    "frequency": "m",
    "maxResults": 50
}

Tips for best results

• Search first, then fetch. Use search mode to discover series IDs, then pass them to observations mode for actual data.
• Use well-known series IDs for common indicators: GDP, UNRATE, CPIAUCSL, FEDFUNDS, DGS10, HOUST, SP500, DEXUSEU.
• Set date ranges to avoid pulling decades of data when you only need recent values.
• Use frequency aggregation to reduce volume. Set frequency to a for annual summaries instead of downloading daily or monthly data.
• Batch series IDs in a single run. Observations and series modes accept multiple IDs, so you can fetch unemployment, GDP, and CPI together.
• Schedule recurring runs on Apify to build automated monitoring pipelines that track key economic indicators over time.

---

Output

Output example (search mode)

{
    "seriesId": "GDP",
    "title": "Gross Domestic Product",
    "frequency": "Quarterly",
    "units": "Billions of Dollars",
    "seasonalAdjustment": "Seasonally Adjusted Annual Rate",
    "observationStart": "1947-01-01",
    "observationEnd": "2025-01-01",
    "lastUpdated": "2025-03-27 07:56:06-05",
    "popularity": 95,
    "notes": "BEA Account Code: A191RC. Gross domestic product (GDP), the featured measure of U.S. output, is the market value of the goods and services produced by labor and property located in the United States.",
    "extractedAt": "2025-04-15T14:30:00.000Z"
}

Output example (observations mode)

{
    "seriesId": "UNRATE",
    "title": "Unemployment Rate",
    "date": "2023-06-01",
    "value": "3.6",
    "units": "Percent",
    "frequency": "Monthly"
}

Output fields

Search and series mode:

Field	Type	Description
seriesId	String	FRED series identifier (e.g., GDP, UNRATE).
title	String	Full descriptive name of the series.
frequency	String	Reporting frequency (e.g., "Quarterly", "Monthly").
units	String	Measurement units (e.g., "Billions of Dollars", "Percent").
seasonalAdjustment	String	Seasonal adjustment method applied.
observationStart	String	Earliest available observation date.
observationEnd	String	Most recent observation date.
lastUpdated	String	Timestamp of the last data update.
popularity	Number	FRED popularity ranking (0--100).
notes	String	Descriptive notes and methodology.
extractedAt	String	ISO 8601 timestamp of when the actor ran.

Observations mode:

Field	Type	Description
seriesId	String	FRED series identifier.
title	String	Full descriptive name of the series.
date	String	Observation date in YYYY-MM-DD format.
value	String	Data value for the observation.
units	String	Measurement units.
frequency	String	Reporting frequency of the series.

---

Use cases

• Economic research -- download GDP, inflation, and employment data for academic papers, policy analysis, or forecasting models.
• Financial analysis -- track interest rates (FEDFUNDS, DGS10), treasury yields, and money supply (M2SL) for investment decision-making.
• Automated dashboards -- schedule daily or weekly runs to feed economic indicators into Google Sheets, Tableau, or Power BI.
• Journalism and reporting -- pull official economic statistics with full metadata and sourcing for data-driven stories.
• Machine learning pipelines -- collect historical time series data to train forecasting models on unemployment (UNRATE), housing starts (HOUST), or consumer prices (CPIAUCSL).
• Cross-indicator comparison -- batch-fetch multiple series in one run to compare GDP growth against inflation, employment, or trade balance trends.

Popular FRED series IDs

Series ID	Description	Frequency
GDP	Gross Domestic Product	Quarterly
UNRATE	Unemployment Rate	Monthly
CPIAUCSL	Consumer Price Index (All Urban)	Monthly
FEDFUNDS	Federal Funds Effective Rate	Monthly
DGS10	10-Year Treasury Constant Maturity	Daily
HOUST	Housing Starts	Monthly
SP500	S&P 500 Index	Daily
M2SL	M2 Money Supply	Monthly
DEXUSEU	US/Euro Exchange Rate	Daily
PAYEMS	Total Nonfarm Payrolls	Monthly

---

API and integration

Use the Apify API to run FRED Economic Data Search programmatically. The actor ID is gz0VOFSLZkFwhqOS8.

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("ryanclinton/fred-economic-data").call(run_input={
    "apiKey": "your_fred_api_key",
    "mode": "observations",
    "seriesIds": ["GDP", "UNRATE"],
    "startDate": "2020-01-01",
    "frequency": "q"
})

dataset = client.dataset(run["defaultDatasetId"])
for item in dataset.iterate_items():
    print(f"{item['seriesId']}: {item['date']} = {item['value']} {item['units']}")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_APIFY_TOKEN" });

const run = await client.actor("ryanclinton/fred-economic-data").call({
    apiKey: "your_fred_api_key",
    mode: "search",
    searchText: "consumer price index",
    maxResults: 20,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => console.log(`${item.seriesId}: ${item.title}`));

cURL

curl "https://api.apify.com/v2/acts/gz0VOFSLZkFwhqOS8/runs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -d '{
    "apiKey": "your_fred_api_key",
    "mode": "observations",
    "seriesIds": ["FEDFUNDS"],
    "startDate": "2024-01-01",
    "frequency": "m"
  }'

Integrations

• Google Sheets -- automatically push economic data to spreadsheets for dashboards and reporting.
• Slack / Email -- receive notifications when new data is available after a scheduled run.
• Webhooks -- trigger downstream workflows in Zapier, Make, or n8n when a run completes.
• Apify API -- consume results programmatically from any language or platform.

---

How it works

FRED Economic Data Search
                     =========================

[Input Config]         [FRED API]              [Apify Dataset]
      |                     |                        |
      v                     v                        v
 +---------+     +-------------------+     +------------------+
 | apiKey   |---->| api.stlouisfed.   |---->| Clean JSON       |
 | mode     |     | org/fred          |     | output with      |
 | seriesIds|     |                   |     | metadata         |
 | dates    |     | /series/search    |     |                  |
 | frequency|     | /series           |     | Export: JSON,    |
 | maxResult|     | /series/observ.   |     | CSV, Excel       |
 +---------+     +-------------------+     +------------------+
      |                     |                        |
      v                     v                        v
  Mode routing       Pagination &            Push to dataset
  & validation       missing value           via Actor.pushData
                     filtering (".")

1. The actor reads input configuration and validates required fields based on the selected mode.
2. For search mode, it queries the FRED /series/search endpoint with keywords, paginating through results ordered by popularity in descending order. Each page is processed until the maxResults limit is reached or no more results are available.
3. For observations mode, the actor first fetches /series metadata for each series ID to obtain the title, units, and frequency. It then calls /series/observations with optional date range and frequency parameters. FRED represents missing data points with a "." string value -- the actor automatically filters these out so your dataset contains only valid numeric observations.
4. For series mode, it retrieves /series metadata for each provided series ID, returning the same structured output as search mode.
5. All results are normalized into clean JSON objects and pushed to the Apify dataset, where they can be exported or accessed via the API.

---

Performance and cost

Scenario	Memory	Duration	Est. cost
Search for 50 series	128 MB	~5 sec	~$0.001
Observations for 1 series (1 year, monthly)	128 MB	~5 sec	~$0.001
Observations for 5 series (10 years, monthly)	256 MB	~15 sec	~$0.003
Observations for 10 series (full history)	256 MB	~30 sec	~$0.005
Series metadata for 20 IDs	128 MB	~10 sec	~$0.002

The FRED API key is completely free with no usage fees from the Federal Reserve Bank of St. Louis. Apify platform costs are minimal -- most use cases fit comfortably within the free tier ($5/month in credits). Even heavy users running multiple daily scheduled pulls across dozens of series will typically spend only a few cents per month.

---

Limitations

• API key required. A free FRED API key must be obtained from fred.stlouisfed.org. Without it, the actor runs in dry-run mode only.
• FRED API rate limits. The FRED API does not publish strict rate limits, but excessive requests may be throttled. The actor's pagination handles this gracefully for normal workloads.
• Search limited to 1,000 results. The maxResults parameter caps at 1,000 series per search query.
• Values returned as strings. Observation values are returned as strings (matching FRED's API format) and may need numeric conversion for calculations.
• US-focused data. While FRED includes some international series, the primary coverage is US economic indicators.
• No real-time streaming. The actor fetches a snapshot of data per run. For continuous monitoring, schedule recurring runs on Apify.

---

Responsible use

This actor retrieves data from the FRED API, a public service provided by the Federal Reserve Bank of St. Louis. Please use it responsibly:

• Comply with the FRED API Terms of Use when using retrieved data.
• Attribute data to its original source (Federal Reserve Bank of St. Louis, FRED) in any publications or reports.
• Avoid excessive request volumes that could strain the FRED API infrastructure.
• Do not use this actor to redistribute raw FRED data as a competing data service.

---

FAQ

Do I need a FRED API key? Yes. The actor requires a free API key from the Federal Reserve Bank of St. Louis. Register at fred.stlouisfed.org/docs/api/api_key.html. Registration is free and takes only a few minutes.

What happens if I run without an API key? The actor runs in dry-run mode and outputs step-by-step instructions for obtaining a free API key. No economic data is returned.

What economic data is available through FRED? FRED contains over 840,000 time series from 114 sources, including GDP, employment, inflation, interest rates, exchange rates, housing data, industrial production, consumer sentiment, money supply, government debt, and trade balances. Data primarily covers the United States, with some international series.

How far back does the historical data go? It depends on the series. Some series like GDP go back to 1947. Others may have shorter histories. The observationStart field in search and series results shows the earliest available data point for each series.

Can I get daily or real-time data? Yes. Some FRED series are updated daily, such as DFF (daily Federal Funds effective rate) and DGS10 (10-Year Treasury yield). Use observations mode with the appropriate series ID to fetch the latest values.

How do I find the right series ID? Use search mode with descriptive keywords. For example, searching "consumer price index" returns relevant series ranked by popularity. The top result is usually the most commonly used version of that indicator. Use the returned seriesId value in subsequent observations or series mode runs.

What is frequency aggregation and when should I use it? Frequency aggregation converts data from a higher frequency to a lower one. For example, if a series reports daily values but you only need monthly averages, set frequency to m. The FRED API handles the aggregation server-side, so you receive pre-computed values at your chosen interval. This is useful for reducing data volume, aligning multiple series to the same frequency for comparison, or simplifying analysis when granular data is not needed.

Can I use this actor on a schedule? Yes. Apify supports cron-based scheduling for any actor. You can configure the actor to run daily, weekly, or monthly to automatically pull the latest economic data into your dataset. Combined with integrations like Google Sheets or webhooks, this creates a fully automated economic data monitoring pipeline.

---

Related actors

Actor	Description
BLS US Economic Data Search	Bureau of Labor Statistics data including employment, wages, price indices, and productivity metrics.
World Bank Development Indicators	Global development indicators for cross-country economic comparisons.
OECD Economic Statistics	International economic data from OECD statistical datasets.
IMF Economic Data	International Monetary Fund economic indicators and forecasts.
Finnhub Stock Market Data	Real-time and historical stock market data to complement economic indicators.
Currency Exchange Rate Tracker	Live and historical currency exchange rates for international economic analysis.