Choose a Free Macroeconomic Data API
for Global Indicators选择免费宏观经济数据 API
获取全球经济指标

Free macroeconomic data API: quick answer免费宏观经济数据 API：快速结论

What users need from a macroeconomic data API用户需要宏观经济数据 API 完成什么任务

Searchers usually want a usable economic data API free enough for a prototype, notebook, dashboard, or AI agent. The recurring need is not merely “find GDP.” It is to identify a trustworthy series, retrieve it programmatically, understand its metadata, and keep the integration stable when values are missing or revised.

中文搜索结果更常围绕“宏观经济数据 API”“免费经济数据接口”和具体机构接口展开。用户需要的不只是找到 GDP，而是确认数据出处、指标代码、返回格式、鉴权方式、更新频率和修订规则，并把数据稳定接入研究、看板或 Agent。

Entities and features repeated across current results当前结果反复覆盖的实体与功能

Define the macroeconomic dataset before selecting an API选择 API 前先定义宏观经济数据集

A macroeconomic data API should connect a clearly defined indicator to a geography and statistical period. It is not simply a stream of numbers tagged “GDP” or “inflation.” The useful record includes the indicator concept, country or region, unit, price basis, frequency, seasonal-adjustment status, observation period, release or update time, source institution, and revision status. This page focuses on building comparable country-level macro time series. The broader free economic data API guide is better when the task is first choosing among many economic-data categories.

宏观经济数据 API 应把定义明确的指标连接到地区和统计期，而不是只返回标有“GDP”或“通胀”的数字。可用记录需要包含指标概念、国家或地区、单位、价格口径、频率、季调状态、观测期、发布或更新时间、来源机构和修订状态。本页专注构建可比较的国家级宏观时间序列；如果任务只是先在不同经济数据类别中选择来源，可阅读免费经济数据 API 综合指南。

Compare free macro data API sources比较免费宏观经济数据 API 来源

How to use a macroeconomic data API in Python如何用 Python 获取宏观经济数据

A revision-aware workflow for GDP and inflation data APIs能够处理修订的 GDP 与 CPI 数据流程

Working Python example: compare World Bank GDP growth可运行 Python 示例：比较世界银行 GDP 增速

The World Bank Indicators API v2 does not require an API key. This example requests annual real GDP growth for the United States and China, validates the two-part JSON response, rejects missing observations, and preserves the indicator code and source. It is intentionally annual cross-country data; it should not be mixed with quarterly seasonally adjusted GDP without an explicit transformation.

世界银行 Indicators API v2 无需 API Key。下面的示例请求美国和中国的年度实际 GDP 增速，验证两段式 JSON 响应、剔除缺失观测，并保留指标代码与来源。这是年度跨国数据，不能在没有明确转换的情况下与季度季调 GDP 混用。

import requests

url = (
    "https://api.worldbank.org/v2/country/USA;CHN/"
    "indicator/NY.GDP.MKTP.KD.ZG"
)
params = {
    "date": "2019:2025",
    "format": "json",
    "per_page": 100,
}

response = requests.get(url, params=params, timeout=30)
response.raise_for_status()
payload = response.json()

if not isinstance(payload, list) or len(payload) != 2:
    raise ValueError("Unexpected World Bank response shape")

page, observations = payload
rows = []
for item in observations:
    if item.get("value") is None:
        continue
    rows.append({
        "country_code": item["countryiso3code"],
        "period": int(item["date"]),
        "indicator_code": item["indicator"]["id"],
        "real_gdp_growth_percent": float(item["value"]),
        "source": "World Bank Indicators API v2",
    })

assert rows, "No non-null GDP observations returned"
print(sorted(rows, key=lambda row: (row["country_code"], row["period"]))[-4:])

Normalize macroeconomic data without erasing meaning在不丢失语义的前提下标准化宏观数据

Use a long-form observation schema使用长表结构保存观测值

A durable record separates identity from value. Store provider, dataset, indicator code, country or region code, frequency, observation period, value, unit, multiplier, seasonal adjustment, price basis, transformation, status flag, release time, retrieval time, and source URL. Preserve the provider’s original codes next to normalized labels. A friendly name such as “GDP growth” is not a stable key because several series can share it. Country aggregates also need their own entity type; “Euro area,” “World,” and “High income” are not countries even if an API returns them through a country-shaped endpoint.

可靠的数据记录需要把指标身份与数值分开保存。应记录提供方、数据集、指标代码、国家或地区代码、频率、观测期、数值、单位、缩放倍数、季调状态、价格口径、转换方式、状态标记、发布时间、抓取时间和来源 URL，并同时保留提供方原始代码与标准化标签。“GDP growth”这样的易读名称不是稳定主键，因为多个序列可能同名；欧元区、全球和高收入经济体等聚合对象也应有独立的实体类型，不能因为接口结构相似就把它们当作国家。

Do not compare values until units and periods match单位与时期未对齐前不要比较数值

Convert only when the transformation is mathematically and statistically justified. Current local currency, current U.S. dollars, constant-price national currency, PPP dollars, index levels, annual percentage change, and percent of GDP answer different questions. Quarterly GDP growth can be quarter-over-quarter, annualized quarter-over-quarter, or year-over-year. Monthly inflation can be an index, monthly change, or annual change. Keep the raw value and unit, store the normalized value in a separate field, and record the formula. Never infer seasonal adjustment from frequency alone.

只有数学与统计意义都成立时才能转换。现价本币、现价美元、不变价本币、PPP 美元、指数水平、年度百分比变化和 GDP 占比回答的问题不同。季度 GDP 增速可能是环比、环比年化或同比；月度通胀可能是指数、月环比或年同比。应保留原始数值与单位，把标准化值写入独立字段并记录公式，不能仅根据频率推断季调状态。

Make cross-country macroeconomic comparisons defensible让跨国宏观经济比较经得起复核

Choose a comparison basis that matches the question根据问题选择一致的比较口径

Country comparisons fail when a technically valid number answers the wrong question. Nominal GDP converted at market exchange rates is useful for measuring current-dollar economic size, while purchasing-power-parity GDP addresses a different comparison of domestic purchasing power. Real GDP growth is suited to change over time, but its chain-linked level is not always additive across components or directly comparable in currency terms. GDP per capita changes the denominator again. Write the intended statement first—size, growth, living-standard proxy, fiscal burden, trade exposure, or cyclical momentum—then select the indicator and denominator that support it.

跨国比较最常见的失败，是数值在技术上正确，却回答了错误的问题。按市场汇率转换的名义 GDP 适合衡量当期美元经济规模，PPP GDP 则回答国内购买力意义上的另一类比较；实际 GDP 增速适合观察时间变化，但链式量价水平未必能跨组成项相加，也不能直接按币种比较；人均 GDP 又改变了分母。应先写清楚要表达的是规模、增长、生活水平代理、财政负担、贸易暴露还是周期动量，再选择能支持该结论的指标与分母。

Align geography, period, frequency, and release status对齐地区、时期、频率与发布状态

Use one geographic classification and preserve changes such as country splits, code changes, and regional membership. Align all economies to a common statistical period instead of taking each country’s latest non-null value from a different year. When converting quarterly observations to annual values, define whether to sum flows, average rates, or take end-of-period stocks; one aggregation rule does not work for every series. Display coverage counts and missing economies. If one country’s value is an official observation and another’s is an estimate or forecast, keep that status visible rather than ranking them as equivalent facts.

应使用统一的地区分类，并保留国家拆分、代码变化和区域成员调整等事件。所有经济体应对齐同一统计期，不能从不同年份各取一个最新非空值。把季度数据转为年度数据时，要根据指标定义决定流量求和、比率取平均还是存量取期末值，不存在适用于所有序列的统一聚合规则。结果还应展示覆盖数量与缺失经济体；如果一个国家是官方观测、另一个是估算或预测，必须保留状态，不能把它们作为等价事实直接排名。

Handle releases, revisions, vintages, and forecasts explicitly显式处理发布值、修订值、历史版本与预测

Observation period is not publication time观测期不等于发布时间

A GDP value labeled 2025 may be published in 2026 and revised several times afterward. Store the statistical period, first release time, latest update time, retrieval time, and—when available—vintage or revision identifier separately. For event-driven dashboards, consult the official release calendar instead of polling continuously. For backtests, use the value available to the strategy at the historical decision time; loading today’s revised history into yesterday’s model creates look-ahead bias.

标记为 2025 年的 GDP 数值可能在 2026 年发布，并在之后多次修订。统计期、首次发布时间、最新更新时间、抓取时间，以及可用时的历史版本或修订标识必须分开保存。事件型看板应参考官方发布日历，而不是持续轮询；历史回测必须使用策略当时能够获得的数值，把今天修订后的历史数据放进昨天的模型会产生前视偏差。

Separate actual observations from estimates and forecasts区分实际观测、估算值与预测值

International datasets may combine reported observations, staff estimates, projections, and modeled values. Preserve status flags and forecast horizons. Do not append projections to actual history without a field that distinguishes them. A missing value is not zero, and “latest available” may refer to different years across countries. Cross-country rankings should either align to one common period or clearly display each economy’s observation year and coverage gap.

国际数据集可能混合已报告观测、机构估算、预测和模型值。必须保留状态标记与预测期限，不能在没有区分字段的情况下把预测直接接到实际历史后面。缺失值不是零，“最新可用”在不同国家可能对应不同年份。跨国排名应对齐同一统计期，或明确展示每个经济体的观测年份与覆盖缺口。

Build a production macroeconomic data pipeline构建生产级宏观经济数据管道

Separate discovery, retrieval, validation, and delivery分离发现、抓取、验证与交付

Discovery maps a user request to a provider, dataset, indicator, geography, frequency, and unit. Retrieval follows the provider’s documented pagination and stores the raw response. Validation checks schema, duplicates, nulls, period ordering, units, status flags, and coverage. Normalization creates an internal observation model without destroying source fields. Delivery exposes approved records to a dashboard, notebook, database, API, or agent. This separation makes it possible to reprocess history after a parser or mapping rule changes.

查找阶段把用户需求映射到提供方、数据集、指标、地区、频率与单位；抓取阶段遵循官方分页并保存原始响应；验证阶段检查数据结构、重复记录、空值、时期顺序、单位、状态标记与覆盖范围；标准化阶段建立内部观测模型，同时保留来源字段；交付阶段再把已审核记录提供给看板、Notebook、数据库、API 或 Agent。完成分层后，即使解析器或映射规则发生变化，也可以重新处理历史数据。

Respect pagination, rate limits, and release schedules遵守分页、限流与发布日程

The World Bank response includes page metadata; never assume the default page contains every country or period. OECD’s SDMX service is free but rate limited and recommends focused queries. Cache immutable historical partitions, refresh only periods that can still change, and use bounded retries with backoff for temporary failures. Do not retry invalid indicator codes or permission errors indefinitely. Alert on stale latest periods, disappearing series, sudden null-rate increases, unexpected unit changes, and country coverage dropping below an agreed threshold.

世界银行响应包含分页元数据，不能假设默认页覆盖全部国家与时期。OECD 的 SDMX 服务免费但存在限流，并建议使用聚焦查询。应缓存不再变化的历史分区，只刷新仍可能修订的时期；临时故障可有限退避重试，无效指标代码或权限错误不能无限请求。还要监控最新时期陈旧、序列消失、空值率骤增、单位异常变化以及国家覆盖低于约定阈值。

Design the API workflow around the macroeconomic use case围绕宏观经济使用场景设计 API 工作流

Dashboards and research notebooks看板与研究 Notebook

A public dashboard needs readable definitions, observation periods, latest-update labels, revision notes, units, source links, and graceful treatment of missing countries. A research notebook additionally needs deterministic query parameters, raw-response snapshots, code version, and transformation formulas so results can be reproduced. Precompute common transformations such as year-over-year growth only when the source series and frequency are stable; otherwise calculate them in a versioned research layer and retain the source level.

公开看板需要清晰定义、观测期、最近更新时间、修订说明、单位、来源链接以及对缺失国家的合理处理。研究 Notebook 还需要确定性的查询参数、原始响应快照、代码版本和转换公式，确保结果可复现。只有来源序列与频率稳定时才预计算同比等常用变换；否则应在带版本的研究层计算，并保留来源水平值。

Alerts, nowcasting, and AI agents提醒、即时预测与 AI Agent

A release alert should trigger from the official calendar or a verified new release identifier, not merely from a changed “latest” value that could be a revision. A nowcasting model needs an as-of dataset that records what was available on every model date, including publication lags and revisions. For an AI agent, expose narrow operations such as “retrieve one indicator for named countries and periods,” “search indicator metadata,” or “compare values only after compatibility checks.” Require explicit codes or resolved metadata, cap default result size, and return provider, series, unit, period, status, and retrieval time with every answer.

发布提醒应由官方日历或已验证的新发布标识触发，不能只因为“最新值”变化就报警，因为变化可能只是历史修订。即时预测模型需要按历史时点保存的数据集，记录每个模型时点真正可用的信息，包括发布滞后与修订。面向 AI Agent 时，应把“读取指定国家与时期的单一指标”“搜索指标元数据”或“通过兼容性检查后比较数值”等任务封装成范围明确的操作，要求提供明确代码或已解析的元数据，限制默认结果量，并在每次回答中返回提供方、序列、单位、时期、状态与抓取时间。

QVeris can help discover and inspect these operations and route an agent to a suitable capability. It should not hide whether a value came from the World Bank, IMF, OECD, Eurostat, FRED, or another producer. The agent’s interpretation must remain separate from retrieved facts, and high-impact claims should link back to the original statistical definition and release.

QVeris 可帮助查找并检查这些操作，并让 Agent 调用合适的能力，但不应隐藏数值究竟来自世界银行、IMF、OECD、Eurostat、FRED 还是其他发布机构。Agent 的解释必须与检索到的事实分开；对于影响较大的结论，还应链接回原始统计定义与发布记录。

How QVeris helps discover economic data APIsQVeris 如何帮助发现经济数据 API

• Search by task and indicator instead of guessing a provider name.
• Inspect authentication, required parameters, response shape, and documented limits.
• Keep the original provider, series code, unit, and retrieval timestamp in downstream output.

• 按任务与指标搜索，不必先猜测提供方名称。
• 检查鉴权、必填参数、响应结构与已记录的调用限制。
• 在下游结果中保留原始提供方、序列代码、单位与抓取时间。

FAQ常见问题

External references外部参考链接