# IMF API

> IMF provides World Economic Outlook forecasts and country rankings as a workflow and API.

IMF, also called IMF DataMapper, returns World Economic Outlook figures by year for a country or region supplied as input. IMF ranks countries by a selected World Economic Outlook indicator and year, with an optional sort direction and result limit.

- Page: https://fous.com/tools/imf
- Handle: `@imf`
- Category: [Finance](https://fous.com/tools/category/finance)
- Source website: https://imf.org/external/datamapper
- Last verified: Sep 29, 2026

## Methods

### Get economic forecast

Operation `get_economic_forecast`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get World Economic Outlook figures for a country or region by year, with actual or forecast labels. Unavailable measures are null; some regions have no WEO series.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `country` | string | yes | `"Germany"` | Country or region name, such as Germany, World, or Euro area. |
| `end_year` | integer | no | `2027` | Last year to show, for example 2028. Defaults to two years after the current year. |
| `start_year` | integer | no | `2025` | First year to show, for example 2024. Defaults to the current year. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "country"
  ],
  "properties": {
    "country": {
      "type": "string",
      "description": "Country or region name, such as Germany, World, or Euro area.",
      "examples": [
        "Germany",
        "World",
        "Euro area"
      ]
    },
    "end_year": {
      "type": "integer",
      "description": "Last year to show, for example 2028. Defaults to two years after the current year.",
      "examples": [
        2027,
        2028
      ]
    },
    "start_year": {
      "type": "integer",
      "description": "First year to show, for example 2024. Defaults to the current year.",
      "examples": [
        2025,
        2026
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "country": "Germany"
    },
    {
      "country": "World",
      "end_year": 2027,
      "start_year": 2025
    },
    {
      "country": "Euro area",
      "end_year": 2028,
      "start_year": 2026
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `years` | array |  | Economic measures for each requested year. |
| `years[].year` | integer | `2026` |  |
| `years[].status` | string | `"forecast"` |  |
| `years[].page_url` | string | `"https://www.imf.org/external/datamapper/NGDP_RPCH@WEO/DEU"` |  |
| `years[].gdp_billions_usd` | number or null | `5452.858` |  |
| `years[].inflation_percent` | number or null | `2.7` |  |
| `years[].gdp_per_person_usd` | number or null | `65302.893` |  |
| `years[].unemployment_percent` | number or null | `3.9` |  |
| `years[].real_gdp_growth_percent` | number or null | `0.8` |  |
| `years[].government_debt_percent_of_gdp` | number or null | `64.6` |  |
| `years[].current_account_balance_percent_of_gdp` | number or null | `3.9` |  |
| `country` | string | `"Germany"` | Country or region name. |
| `weo_edition` | string | `"April 2026"` | World Economic Outlook edition. |
| `imf_country_code` | string | `"DEU"` | IMF code for this country or group. |

**Example input**

```json
{
  "country": "Germany"
}
```

**Example output**

```json
{
  "years": [
    {
      "year": 2026,
      "status": "forecast",
      "page_url": "https://www.imf.org/external/datamapper/NGDP_RPCH@WEO/DEU",
      "gdp_billions_usd": 5452.858,
      "inflation_percent": 2.7,
      "gdp_per_person_usd": 65302.893,
      "unemployment_percent": 3.9,
      "real_gdp_growth_percent": 0.8,
      "government_debt_percent_of_gdp": 64.6,
      "current_account_balance_percent_of_gdp": 3.9
    },
    {
      "year": 2027,
      "status": "forecast",
      "page_url": "https://www.imf.org/external/datamapper/NGDP_RPCH@WEO/DEU",
      "gdp_billions_usd": 5642.156,
      "inflation_percent": 2.3,
      "gdp_per_person_usd": 67613.107,
      "unemployment_percent": 3.5,
      "real_gdp_growth_percent": 1.2,
      "government_debt_percent_of_gdp": 66.5,
      "current_account_balance_percent_of_gdp": 3.8
    },
    {
      "year": 2028,
      "status": "forecast",
      "page_url": "https://www.imf.org/external/datamapper/NGDP_RPCH@WEO/DEU",
      "gdp_billions_usd": 5818.884,
      "inflation_percent": 2,
      "gdp_per_person_usd": 69804.854,
      "unemployment_percent": 3.2,
      "real_gdp_growth_percent": 1.2,
      "government_debt_percent_of_gdp": 68.4,
      "current_account_balance_percent_of_gdp": 3.8
    }
  ],
  "country": "Germany",
  "weo_edition": "April 2026",
  "imf_country_code": "DEU"
}
```

### List country rankings

Operation `list_country_rankings`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Rank countries by a World Economic Outlook indicator for a chosen year. Excludes regional and country-group totals and countries without a value; forecast labels follow the indicator’s published projection year.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `year` | integer | no | `2024` | Calendar year to rank, for example 2026. Defaults to the current year. |
| `order` | string | no | `"lowest_first"` | Sort direction, for example highest_first. |
| `indicator` | string | no | `"government_debt"` | Economic measure to rank, for example gdp_growth. |
| `max_results` | integer | no | `7` | Maximum countries to return, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "maximum": 2200,
      "minimum": 1900,
      "description": "Calendar year to rank, for example 2026. Defaults to the current year.",
      "examples": [
        2024,
        2026
      ]
    },
    "order": {
      "enum": [
        "highest_first",
        "lowest_first"
      ],
      "type": "string",
      "default": "highest_first",
      "description": "Sort direction, for example highest_first.",
      "examples": [
        "lowest_first",
        "highest_first"
      ]
    },
    "indicator": {
      "enum": [
        "gdp_growth",
        "inflation",
        "unemployment",
        "gdp",
        "gdp_per_person",
        "government_debt"
      ],
      "type": "string",
      "default": "gdp_growth",
      "description": "Economic measure to rank, for example gdp_growth.",
      "examples": [
        "government_debt",
        "gdp_growth",
        "unemployment"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 200,
      "minimum": 1,
      "description": "Maximum countries to return, for example 20.",
      "x-fous-developer": true,
      "examples": [
        7,
        20,
        5
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "year": 2024,
      "order": "lowest_first",
      "indicator": "government_debt",
      "max_results": 7
    },
    {
      "year": 2026,
      "order": "highest_first",
      "indicator": "gdp_growth",
      "max_results": 20
    },
    {
      "year": 2026,
      "order": "lowest_first",
      "indicator": "unemployment",
      "max_results": 5
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `unit` | string | `"% of GDP"` | Unit of the country values. |
| `year` | integer | `2024` | Calendar year of the rankings. |
| `rankings` | array |  |  |
| `rankings[].rank` | integer | `1` |  |
| `rankings[].value` | number | `0` |  |
| `rankings[].country` | string | `"Macao SAR"` |  |
| `rankings[].page_url` | string | `"https://www.imf.org/external/datamapper/GGXWDG_NGDP@WEO/MAC"` | IMF DataMapper page for this indicator and country. |
| `indicator` | string | `"Government debt"` | Plain name of the economic measure. |
| `data_status` | string | `"Actual"` | Whether the chosen year precedes the forecast cutoff. |

**Example input**

```json
{
  "year": 2024,
  "order": "lowest_first",
  "indicator": "government_debt",
  "max_results": 7
}
```

**Example output**

```json
{
  "unit": "% of GDP",
  "year": 2024,
  "rankings": [
    {
      "rank": 1,
      "value": 0,
      "country": "Macao SAR",
      "page_url": "https://www.imf.org/external/datamapper/GGXWDG_NGDP@WEO/MAC"
    },
    {
      "rank": 2,
      "value": 0.5,
      "country": "Liechtenstein",
      "page_url": "https://www.imf.org/external/datamapper/GGXWDG_NGDP@WEO/LIE"
    },
    {
      "rank": 3,
      "value": 1.6,
      "country": "Brunei Darussalam",
      "page_url": "https://www.imf.org/external/datamapper/GGXWDG_NGDP@WEO/BRN"
    }
  ],
  "indicator": "Government debt",
  "data_status": "Actual"
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@imf",
  "visibility": "public",
  "operation": "get_economic_forecast",
  "version": 1,
  "input": {
    "country": "Germany"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@imf\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_economic_forecast\",\n  \"version\": 1,\n  \"input\": {\n    \"country\": \"Germany\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@imf",
  "visibility": "public",
  "operation": "get_economic_forecast",
  "version": 1,
  "input": {
    "country": "Germany"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/imf`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_economic_forecast`: Get economic forecast. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `list_country_rankings`: List country rankings. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-imf https://api.fous.com/mcp/tools/imf --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Compare economic forecasts across countries and years
- Track projected inflation and unemployment
- Rank countries by economic growth
- Review government debt as a share of GDP
- Compare GDP per person across regions

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this IMF tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a IMF account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from imf.org when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What are the economic forecasts for a country or region?

Get economic forecast returns World Economic Outlook figures by year, including actual or forecast labels, for the supplied country or region.

### Which countries rank highest for an economic indicator?

List country rankings ranks countries by a selected World Economic Outlook indicator and year, with an optional sort direction and result limit.

## Related

- [World Bank API](https://fous.com/tools/world-bank.md): World Bank provides country statistics and latest values within selected years, plus country rankings for a chosen year or the latest broadly covered year.
- [Trading Economics API](https://fous.com/tools/trading-economics.md): Trading Economics provides economic indicators, market data and country statistics, including country overviews, latest reported country comparisons and current commodity prices reflecting reported trading days.
- [FIFA API](https://fous.com/tools/fifa.md): FIFA provides official men’s and women’s national-team rankings, excluding unranked teams, and year-specific tournament matches with scores, teams, stages and venues.
- [World Health Organization API](https://fous.com/tools/world-health-organization.md): The World Health Organization provides public health information, latest outbreak reports, country health statistics with up to 10 years of history when available, and topic fact sheets.
- [FRED API](https://fous.com/tools/fred.md): FRED provides public economic series, observations, latest values, sources, and popular topic searches with coverage dates and metadata; freshness varies by series.
- [CompaniesMarketCap API](https://fous.com/tools/companiesmarketcap.md): CompaniesMarketCap ranks public companies worldwide or by country and industry across size and financial measures, and provides company figures with market-cap history for completed years.
- [Investing.com API](https://fous.com/tools/investing-com.md): Investing.com provides financial markets data and news, economic releases up to 31 days, and current commodity prices and government bond yields, which may be delayed or indicative.
- [Our World in Data API](https://fous.com/tools/our-world-in-data.md): Research and data on global challenges and long-term trends.
- [All Finance tools](https://fous.com/tools/category/finance)