Forecasts API reference
IMF World Economic Outlook forecasts by country, indicator and edition
Overview
What the IMF World Economic Outlook (WEO) expects for a country: one indicator at a time, year by year, from the IMF DataMapper. Every request needs a Bearer key, and REST and MCP draw on one credit balance.
A country is its ISO 3166 alpha-3 code, such as USA or IDN. The indicators are gdp_, inflation (the average of the year), inflation_, unemployment, current_, government_, government_ and gdp_. Every value is a decimal string; unit says whether it is a percent, a percent of GDP or billions of US dollars.
Every answer names its publisher and its edition, the year and month of the WEO round the figures come from, such as 2026-10. The WEO comes out in April and October. Every edition is kept, so edition asks what the IMF expected in an earlier round; without it you get the latest.
Base URL: https:/. Each route below is an MCP tool of its own, with the same parameters.
What every account gets
| What | Every account |
|---|---|
| One country and indicator | One Economics call |
See pricing for what a call costs. A request is charged at the price of its API unless a route says otherwise.
- Only the edition's own year and later are served, and every value is a forecast. The IMF's service does not say where a country's actual figures end, so past years are left out; the economics routes carry them.
- A country the IMF leaves blank for an indicator, or that the IMF does not forecast at all, is 404 not_covered. Some series stop early; the years the IMF does not give are not in the answer.
- An edition is stored when the content of the IMF's answers differs from the latest edition we hold, checked weekly, never on a new name alone. An edition we do not hold is 404 not_found.
- The figures are the IMF's, republished unchanged, and are for analysis, not financial, investment, legal or tax advice.
Endpoints
Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.
Get an official forecast for a country
GET /v1/economics/{country}/forecasts
The IMF World Economic Outlook's forecast of one indicator for one country, year by year from the edition's own year. edition names the WEO round; omit it for the latest.
MCP: tool economics_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
country | path | Yes | string | |
indicator | query | No | string | |
edition | query | No | string |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
country | string | Always | |
indicator | one of gdp_growth, inflation, inflation_end_of_period, unemployment, current_account_gdp, government_debt_gdp, government_balance_gdp, gdp_usd | Always | |
unit | string | Always | |
publisher | always "IMF World Economic Outlook" | Optional | |
edition | string | Always | |
values | list of object | Always | |
values[].year | integer | Always | |
values[].value | string | Always |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/economics/IDN/forecasts?indicator=gdp_growth"{
"country": "IDN",
"indicator": "gdp_growth",
"unit": "percent",
"publisher": "IMF World Economic Outlook",
"edition": "2026-10",
"values": [
{
"year": 2026,
"value": "5.1"
},
{
"year": 2027,
"value": "5.1"
},
{
"year": 2028,
"value": "5.2"
},
{
"year": 2029,
"value": "5.2"
},
{
"year": 2030,
"value": "5.2"
},
{
"year": 2031,
"value": "5.2"
}
]
}Errors
Errors use the shared problem shape with a request_. See Errors and credits for the shape and the credit headers. Failed requests are not charged.
| Code | Status | Meaning |
|---|---|---|
invalid_ | 400 | A parameter is missing, unknown, repeated or outside its range. |
not_ | 404 | No forecast edition with that name is stored. Not charged. |
not_ | 404 | The IMF gives no figure for this country and indicator in this edition. Not charged. |
insufficient_ | 402 | Your credit balance is less than the request costs. |
economics_ | 503 | No edition has been stored yet, or the stored data cannot answer. Not charged. |
Was this page helpful?