Use the Free FRED Data API
with Python and JSON使用免费 FRED 数据 API
获取经济时间序列

TL;DR快速结论

What people want from a free FRED data API用户搜索免费 FRED 数据 API 时要完成什么

The dominant intent is practical and informational: confirm that the FRED API is free, learn whether an API key is required, find the endpoint for series observations, and see working JSON or Python examples. Secondary needs include searching series, understanding quotas, retrieving releases, and using real-time periods or vintage dates for reproducible research.

核心需求是确认 FRED API 是否免费、是否需要 API Key、哪个端点用于序列观测值，以及如何用 JSON 或 Python 发起真实请求。次要需求包括搜索序列、了解调用额度、读取发布信息，以及通过实时区间（real-time period）或历史版本日期（vintage date）完成可复现研究。

Data and features repeated across ranking pages排名页面反复覆盖的数据与功能

Repeated entities and fields include the Federal Reserve Bank of St. Louis, FRED, ALFRED, series IDs, observations, releases, categories, tags, units, frequency, seasonal adjustment, API keys, file types, limits, pagination, realtime_start, realtime_end, and vintage dates.

反复出现的实体与字段包括圣路易斯联储、FRED、ALFRED、序列 ID、观测值、发布、分类、标签、单位、频率、季调、API Key、文件类型、额度、分页、realtime_start、realtime_end 和历史版本日期。

Free FRED data API endpoints to use常用的免费 FRED 数据 API 端点

FRED API access is free, but requests require an API key and remain subject to current terms and limits. Keep the key in server-side configuration or a secret manager rather than embedding it in public client code.

FRED API 可免费使用，但请求需要 API Key，并受当前条款与限制约束。应把 Key 放在服务端配置或密钥管理系统中，不能写入公开客户端代码。

How to use the free FRED data API如何调用免费 FRED 数据 API

1. Create a key and choose a series ID1. 创建 Key 并选择序列 ID

Create a FRED account and request an API key, then identify a series such as GDP, CPIAUCSL, UNRATE, or FEDFUNDS. Do not infer meaning from the short ID alone; inspect the series title, units, frequency, seasonal adjustment, notes, source, and observation dates.

创建 FRED 账户并申请 API Key，然后选择 GDP、CPIAUCSL、UNRATE 或 FEDFUNDS 等序列。不能只依据短 ID 判断含义；还要检查标题、单位、频率、季调、说明、来源与观测日期。

2. Request metadata before observations2. 先请求元数据，再获取观测值

Call /fred/series for the chosen ID before downloading values. This verifies that the identifier exists and gives the metadata needed to label a chart or database column accurately.

下载数值前先调用 /fred/series 检查目标 ID。这可以确认序列存在，并取得准确标注图表或数据库字段所需的元数据。

3. Make a small JSON request3. 发起小范围 JSON 请求

curl "https://api.stlouisfed.org/fred/series/observations?series_id=GDP&api_key=YOUR_KEY&file_type=json&observation_start=2020-01-01" retrieves GDP observations from the selected start date. Replace YOUR_KEY at runtime, never in public source control.

curl "https://api.stlouisfed.org/fred/series/observations?series_id=GDP&api_key=YOUR_KEY&file_type=json&observation_start=2020-01-01" 可获取指定日期后的 GDP 观测值。运行时替换 YOUR_KEY，不要提交到公开代码仓库。

4. Add caching, retries, and provenance4. 加入缓存、重试和出处记录

Cache to match the release schedule, respect retry guidance, record retrieval time and series metadata, preserve the source URL, and monitor schema changes.

按发布日程缓存，遵循重试建议，记录抓取时间和序列元数据，保留来源 URL，并监控数据结构变化。

Validate a FRED API response before publishing it发布前验证FRED API 响应

A successful HTTP status only proves that the FRED server answered. It does not prove that the returned series is the one your application intended to use. Inspect the original source, series identifier, frequency, unit, geography, seasonal-adjustment status, observation date, and release context in every response. Treat missing values as missing rather than zero, preserve status flags, and compare several observations with the visible FRED series page before approving an integration.

HTTP 请求成功只说明服务器已响应，并不能证明返回的 FRED 序列符合应用需求。应检查序列 ID、原始来源、频率、单位、缩放倍数、地区、季调口径、观测日期、实时区间和发布状态。缺失值不能转成零，并应把多个样本值与 FRED 序列页面或原始发布机构逐项核对。

Keep raw data, provenance, and revision history保留原始数据、出处和修订历史

Store the raw response together with the request URL, parameters, retrieval timestamp, HTTP status, and relevant headers. A normalized record should retain the original provider code and series ID so a reviewer can reproduce the call. FRED time series may be corrected, rebased, seasonally adjusted again, or replaced with final observations. Decide whether the product always shows the latest vintage or preserves the value available on each retrieval date. Log schema changes and unexpected empty responses separately from network failures, and use bounded retries only for temporary errors.

For high-impact dashboards, alerts, or agent answers, add a release-date check before delivery. Confirm that the latest period is actually published, that a revised observation did not trigger a duplicate alert, and that a fallback source uses the same statistical concept. Display the observation date and retrieval time separately so users can distinguish when a value applies from when the application fetched it. Record the check result for later operational review and incident analysis.

应把原始响应与请求 URL、参数、抓取时间、HTTP 状态和相关响应头一起保存；标准化记录仍需保留 FRED 序列 ID。经济时间序列可能更正、换基、重新季调，初值也可能被终值替代，因此要明确是展示最新版本，还是保存各个历史版本，并区分数据结构变化、异常空响应与网络错误。

Official FRED API vs aggregated economic data APIs官方 FRED API 与经济数据聚合 API 怎么选

Use the official FRED API when you need FRED series metadata, release relationships, real-time periods, or vintage dates exactly as published. An aggregator may simplify a multi-provider application through one normalized schema, but it can rename fields, transform values, or update later than FRED. Preserve the original FRED series ID and source notes even when a normalized service sits in front of the official endpoint.

需要准确使用 FRED 序列元数据、发布关系、实时区间或历史版本日期时，应优先使用官方 FRED API。聚合 API 可以用统一的数据结构简化多来源接入，但可能重命名字段、转换数值或晚于 FRED 更新；即使采用聚合服务，也应保留原始 FRED 序列 ID 和来源说明。

When an aggregator is the better engineering choice什么时候更适合使用聚合 API

An aggregator is useful when the application needs one query model across several providers or countries. A normalized catalog can reduce discovery time, standardize common fields, and simplify prototypes, dashboards, comparative research, or agent tools. That convenience does not transfer authority to the aggregator. Always retain the original provider code, dataset code, series identifier, unit, frequency, retrieval timestamp, and source URL. Review whether the aggregator transforms values, renames dimensions, changes missing-value markers, delays updates, or applies a separate license. For high-impact outputs, compare representative observations with the original portal and define a fallback path to the producer’s service.

需要统一查询多个国家或提供方时，聚合 API 更适合原型、跨国看板和 Agent 工具，但不会取代原始机构的权威性。应保存提供方、数据集与序列 ID、单位、频率、抓取时间和来源 URL，并检查数值转换、更新延迟和许可；重要结果仍需与官方门户核对。

Validate metadata, revisions, and data quality before use使用前验证元数据、修订与数据质量

Do not treat a series label as a complete definition不要把序列名称当作完整定义

Two series can share a familiar label while measuring different concepts. An “interest rate” may be a policy target, an effective overnight rate, a lending facility rate, a deposit facility rate, or a monthly average. Inflation may be headline or core, monthly or annual, seasonally adjusted or unadjusted, preliminary or final. Before storing observations, capture the title, description, unit, multiplier, frequency, seasonal-adjustment status, geography, counterpart, valuation basis, and collection method. If the API provides dimension labels or codelists, store those mappings rather than relying only on compact codes.

名称相似的序列可能衡量不同概念。“利率”可能是政策目标、隔夜利率或月度均值；通胀也有总体与核心、环比与同比、季调与未季调之分。入库前应保存定义、单位、倍数、频率、季调状态、地区和采集方法，并保留维度代码与标签的映射。

Design explicitly for revisions and missing observations显式处理修订值与缺失观测

Economic time series are revised. A provider may correct an error, incorporate a benchmark survey, rebase an index, change seasonal factors, or replace an estimate with a final value. Decide whether your product needs the latest vintage or the value known at a historical point in time. Preserve retrieval timestamps and, when available, release or vintage identifiers. Do not silently convert missing values to zero. Keep provider status flags, distinguish “not available” from “not applicable,” and test how the parser handles blank strings, symbols, nulls, and suppressed values. Validation rules should detect unexpected frequency changes, duplicate periods, unit changes, large discontinuities, and disappearing series.

经济序列会因更正、换基或估算值转为终值而修订。应决定使用最新版本，还是保存各历史时点当时可得的数据，并记录抓取时间、发布批次或历史版本标识。不要把缺失值转成零；校验规则还应识别频率变化、重复时期、单位变化、异常断点和序列下线。

Build a reliable production integration构建可靠的生产级数据接入

Separate discovery, retrieval, normalization, and delivery分离发现、抓取、标准化与交付

A maintainable pipeline gives each stage one responsibility. Discovery resolves a human request to a provider, dataset, and series. Retrieval calls the documented endpoint and stores the raw response with HTTP status, headers, request parameters, and retrieval time. Normalization converts dates, units, codes, and missing-value conventions into an internal schema without destroying the source representation. Delivery exposes the verified records to a dashboard, research notebook, database, API, or agent capability. Keeping the raw payload makes later debugging and reprocessing possible when a provider changes its schema or a transformation rule is corrected.

数据管道应分离发现、抓取、标准化和交付。抓取阶段保存原始响应、HTTP 状态、请求参数和时间；标准化阶段统一日期、单位和缺失值，但保留原始表达；交付阶段再向看板、数据库、API 或 Agent 提供已验证数据。保留原始响应便于重新处理。

Match polling, caching, and retries to the release schedule让轮询、缓存和重试匹配发布日程

FRED series update on different release schedules. Use series frequency and release metadata to choose a refresh interval, cache stable history, and avoid reloading every observation when only recent periods can change. Apply bounded retries to temporary failures, but do not retry an invalid key or series ID indefinitely. Keep API keys outside client code and alert on stale data, repeated failures, or unexpected empty responses.

不同 FRED 序列按各自发布日程更新。应依据频率和发布元数据设置刷新周期、缓存稳定历史数据，并避免近期数值变化时重拉全部观测。只对临时错误有限重试；无效 Key 或序列 ID 不应无限重试。API Key 必须放在客户端代码之外，并监控陈旧数据、连续失败和异常空响应。

Common applications for the FRED data APIFRED 数据 API 的常见应用场景

Research, dashboards, alerts, and AI agents研究、看板、提醒与 AI Agent

Researchers may combine policy rates, inflation, exchange rates, and monetary aggregates to study transmission mechanisms or compare economic cycles. Product teams may use the same series in internal dashboards, country profiles, treasury tools, or release alerts. Each use case needs a different freshness and revision policy. A historical paper may require a reproducible snapshot, while an operational dashboard usually needs the latest published value plus a visible “last updated” time. An alerting system needs idempotent release detection so a revision does not look like a new period.

政策利率、通胀、汇率和货币总量可用于政策研究、跨国比较、内部看板、国家概览和发布提醒。历史研究强调可复现快照，运营看板需要最新值与更新时间，提醒系统则要避免把数据修订误判为新一期发布。

For an AI agent, expose narrow, documented operations such as “search FRED series,” “retrieve observations for a series and date range,” or “list vintage dates.” Define required parameters, output fields, units, error states, and provenance. Limit the amount of data returned by default and require explicit date ranges for large downloads. The agent should cite FRED, the original producer, and the series ID, state the observation date, and distinguish retrieved facts from interpretation. QVeris can help discover, inspect, call, and audit these capabilities while the statistical producer remains authoritative for values and methodology.

For Python applications, use an environment variable for the API key, set a request timeout, call raise_for_status(), and parse missing observation markers explicitly. Store the exact request parameters with each imported batch so a later run can reliably reproduce the same series, date window, transformation, and real-time period.

Python 应用应通过环境变量读取 API Key，设置请求超时，检查 HTTP 错误，并显式处理缺失观测标记。每批导入数据还应保存完整请求参数，以便复现相同的序列、日期范围、转换方式和实时区间。

面向 AI Agent 时，应把“获取最新利率”“按日期读取序列”“搜索元数据”等任务封装成范围明确的操作，并说明参数、地区、字段、单位、错误和出处。Agent 输出应注明发布机构、序列和观测日期，并区分检索到的事实与模型生成的解释。QVeris 可帮助调用和保留审计记录，官方机构仍是权威来源。

How QVeris helps with the FRED data APIQVeris 如何帮助接入 FRED 数据 API

• Use the QVeris Tool Finder to explore capabilities relevant to economic or financial data.
• Inspect an operation’s parameters and response shape before an agent calls it.
• Keep the provider URL, timestamp, series ID, and license context in downstream records.

• 使用 QVeris 工具查找器探索经济或金融数据相关能力。
• 在 Agent 调用前检查操作参数和响应结构。
• 在下游记录中保留提供方 URL、时间戳、序列 ID 和许可信息。

FAQ

External references外部参考链接