# 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/workflows/imf
- Handle: `@imf`
- Category: [Finance](https://fous.com/workflows/category/finance)
- Source website: https://imf.org/external/datamapper
- Last verified: Sep 29, 2026
- Fous is not affiliated with IMF.

## Methods

### Get economic forecast

Operation `get_economic_forecast`, version 1. 1 credit per call.

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 call.

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

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_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.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

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=120) 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.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_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);
```

Or describe the data in plain language: send `{"api":"@imf","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## 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

### Is Fous affiliated with IMF?

No. Fous is not affiliated with IMF. This workflow reads the public imf.org website and returns its data.

### How much does it cost?

Each run costs 1 credit. 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; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check 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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/our-world-in-data.md): Research and data on global challenges and long-term trends.
- [All Finance workflows](https://fous.com/workflows/category/finance)