Free Macroeconomic Data API

Free macroeconomic data API: quick answer

What users need from a macroeconomic data 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.

Entities and features repeated across current results

Define the macroeconomic dataset before selecting an 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.

Compare free macro data API sources

How to use a macroeconomic data API in Python

A revision-aware workflow for GDP and inflation data APIs

Working Python example: compare World Bank GDP growth

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.

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.

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.

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.

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.

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.

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.

Design the API workflow around the macroeconomic use case

Dashboards and research notebooks

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.

Alerts, nowcasting, and AI agents

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.

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.

How QVeris helps discover economic data APIs

• 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