What does a whole country's economy look like as an API response?

Ask for the inflation history of the United States and you get back something surprisingly modest: a flat JSON array, one object per year, six keys each. No nesting, no metadata block, no units field. Learning to read that array — and to notice what it does not contain — is most of what macro data literacy is.

The call and the shape

GET /macro-indicator/{country} takes the country as an ISO Alpha-3 code in the path (USA, DEU, FRA), an indicator query parameter, and fmt as json or csv. If you omit indicator you get gdp_current_usd by default, which is a genuine trap: forget the parameter and you will silently be handed GDP when you wanted inflation.

There are 39 indicator codes. The ones you will reach for most are gdp_current_usd, gdp_growth_annual, gdp_per_capita_usd, inflation_consumer_prices_annual, consumer_price_index, unemployment_total_percent, debt_percent_gdp and real_interest_rate. The rest run from population_total and life_expectancy through to co2_emissions_tons_per_capita and internet_users_per_hundred — this is a World-Bank-shaped catalogue, so it is broad and shallow rather than deep and financial.

Each element has exactly six fields:

• CountryCode and CountryName — "USA", "United States"
• Indicator — the human label, e.g. "Inflation, consumer prices (annual %)"
• Date — the end of the period the value describes, not the day it was published
• Period — here, "Annual"
• Value — a bare number with no unit attached

A real response

Calling /macro-indicator/USA?indicator=inflation_consumer_prices_annual returns 65 rows, newest first, one per year from 1960 to 2024, starting:

• 2024-12-31 → 2.9495
• 2023-12-31 → 4.1163
• 2022-12-31 → 8.0028
• 2021-12-31 → 4.6979

and running back to 1960-12-31 → 1.4580. The 1980 row reads 13.5492; the 2009 row reads −0.3555, an outright fall in the price level.

Notice that Value is 2.9495 and not "2.95%". The Indicator label is the only place the percent lives. Several indicators in this catalogue are levels (consumer_price_index, population_total, gdp_current_usd), several are percentages, several are ratios of GDP, and several are per-capita amounts. Nothing in the payload tells you which. You read the label, or you read the docs.

Coverage is per series, not global

The obvious assumption — that every country's series ends in the same year — is false. On the same day, USA + inflation_consumer_prices_annual ends at 2024-12-31, while DEU + gdp_growth_annual runs one year further, to 2025-12-31 with a value of 0.2396. Different indicators are compiled by different upstream bodies on different schedules, and the endpoint reports whatever exists.

If you build a cross-country comparison table by taking "the last row" for each country, you will end up comparing 2024 against 2025 and calling it a ranking. Always align on the Date you asked for, not on the array position.

Try it now

1. Here is /macro-indicator/USA?indicator=gdp_growth_annual; /macro-indicator/USA?indicator=inflation_consumer_prices_annual is the second table of step 2. Compare the first Date in each array — growth runs to 2025 and inflation stops at 2024. The edge is per series, not per country: German and American growth both end on the same date, and it is the indicator that moves the boundary.

2. Here is the same country called twice, first with indicator=consumer_price_index and then with indicator=inflation_consumer_prices_annual. Put the two Value columns side by side for the same years and work out which is a level and which is a rate. Nothing but the Indicator string tells you.

3. Here is the inflation call again with &fmt=csv, its first three lines as they arrived on 28 September 2026:

CountryCode,CountryName,Indicator,Date,Period,Value
USA,"United States","Inflation, consumer prices (annual %)",2024-12-31,Annual,2.9495
USA,"United States","Inflation, consumer prices (annual %)",2023-12-31,Annual,4.1163

Check that the CSV carries the same six columns as the JSON, and find where the percent sign lives in it. The format changes; the ambiguity about units does not.