IMF World Economic Outlook Data Scraper

Export IMF World Economic Outlook data as normalized country-indicator-year records for research tables, forecasts, dashboards, and recurring macroeconomic model refreshes.

Choose official WEO indicator codes, IMF country codes, a year range, and historical or forecast periods. The Actor validates the selection against current IMF metadata and writes clean rows to the default Apify dataset.

What this Actor does

The Actor reads the public IMF DataMapper API and turns nested time-series responses into integration-ready records.

It can:

• select up to 12 World Economic Outlook indicators per run;
• select up to 50 countries per run;
• return years from 1980 through the current IMF forecast horizon;
• filter historical years, forecast years, or both;
• attach indicator names, units, edition, and source provenance;
• cap output deterministically with maxItems;
• export through Apify as JSON, CSV, Excel, XML, or RSS.

No IMF API key, browser, login, cookie, or proxy is required.

Who is it for

This Actor is designed for:

• economists refreshing country outlook workbooks;
• analysts comparing growth, inflation, unemployment, or debt forecasts;
• data engineers loading WEO observations into a warehouse;
• investment and risk teams maintaining macroeconomic model inputs;
• researchers who need repeatable provenance for an IMF release;
• automation teams scheduling a dataset refresh after WEO updates.

It is a focused WEO observation exporter. It does not combine unrelated IMF datasets or calculate investment recommendations.

Why use this Actor

IMF DataMapper responses group many countries and years inside nested objects. This Actor handles metadata lookup, code validation, filtering, flattening, output limits, retry behavior, and Apify dataset delivery.

Each row carries both a stable code and a human-readable label. This makes the output suitable for joins while remaining understandable in spreadsheets.

The Actor also labels periods consistently:

• historical: a year before the WEO edition year;
• forecast: the WEO edition year or a later year.

This transparent rule is useful for automation. It is a convenience classification based on the release year, not an IMF row-level forecast flag.

Getting started

1. Open the Actor in Apify Console.
2. Enter one or more WEO indicator codes.
3. Enter IMF country codes such as USA, DEU, CHN, BRA, or IND.
4. Set the inclusive start and end years.
5. Choose historical periods, forecast periods, or both.
6. Set maxItems to bound the exported observations.
7. Click Start.
8. Open the default dataset and export in your preferred format.

The prefilled input returns real GDP growth and inflation for the United States, Germany, and China.

Input parameters

Field	Type	Default	Meaning
indicators	string array	NGDP_RPCH, PCPIPCH, LUR	Official WEO indicator codes; 1–12 values.
countries	string array	USA, DEU, CHN	IMF DataMapper country codes; 1–50 values.
startYear	integer	2020	First year included, minimum 1980.
endYear	integer	2031	Last year included; source availability varies.
observationTypes	string array	historical + forecast	Period classifications to keep.
maxItems	integer	20	Maximum rows saved, from 1 to 10,000.

Codes are case-insensitive in input and normalized to uppercase. Duplicate codes are removed.

Unknown countries, unknown indicators, non-WEO indicators, reversed year ranges, and invalid limits fail clearly instead of silently returning misleading data.

Common WEO indicator codes

The IMF can add or revise metadata. The current metadata endpoint remains the authority.

Useful examples include:

Code	Typical meaning
NGDP_RPCH	Real GDP growth, annual percent change
PCPIPCH	Inflation, average consumer prices
LUR	Unemployment rate
GGXWDG_NGDP	General government gross debt as percent of GDP
BCA_NGDPD	Current account balance as percent of GDP
NGDPD	GDP at current prices in U.S. dollars

The output includes the current label and unit from IMF metadata, so downstream systems do not have to maintain a separate label table.

Output fields

Each default-dataset item represents one indicator for one country and one year.

Field	Description
countryCode	IMF country code.
countryName	Country name from current IMF metadata.
indicatorCode	Official WEO indicator code.
indicatorName	Current human-readable indicator name.
unit	Unit supplied by IMF, or null when unavailable.
year	Observation year.
value	Numeric IMF observation.
observationType	historical or forecast using the documented edition-year rule.
edition	WEO release parsed from IMF metadata, such as April 2026.
dataset	WEO.
sourceUrl	Official IMF API endpoint for the series.
sourceLastModified	IMF metadata timestamp, or null.
retrievedAt	UTC time when the Actor fetched the data.

Example input

{
  "indicators": ["NGDP_RPCH", "PCPIPCH"],
  "countries": ["USA", "DEU", "CHN", "BRA", "IND"],
  "startYear": 2022,
  "endYear": 2030,
  "observationTypes": ["historical", "forecast"],
  "maxItems": 100
}

Example output

A current local run produced this shape:

{
  "countryCode": "USA",
  "countryName": "United States",
  "indicatorCode": "NGDP_RPCH",
  "indicatorName": "Real GDP growth",
  "unit": "Annual percent change",
  "year": 2022,
  "value": 2.5,
  "observationType": "historical",
  "edition": "April 2026",
  "dataset": "WEO",
  "sourceUrl": "https://www.imf.org/external/datamapper/api/v1/NGDP_RPCH",
  "sourceLastModified": "2026-04-08 16:07:34",
  "retrievedAt": "2026-09-13T06:30:00.000Z"
}

Values, editions, timestamps, and forecast horizons can change when IMF updates the source.

How much does it cost to export IMF WEO observations?

Pay-per-event pricing has two parts:

• Actor start: $0.004 per run;
• WEO observation: tiered per saved country-indicator-year row.

Current observation prices are:

Plan	Price per observation
Free	$0.00368
Bronze	$0.00320
Silver	$0.002496
Gold, Platinum, Diamond	$0.00192

At Bronze rates, 100 observations cost about $0.324 including the start event, and 1,000 observations cost about $3.204. Apify displays the applicable plan and maximum charge before a run.

Only useful rows written to the dataset trigger the observation event. Invalid selections and missing values are not charged as observations.

Recurring model refresh workflow

For a repeatable macro model update:

1. Save a Task with stable country and indicator selections.
2. Choose both historical and forecast periods for a complete model window.
3. Schedule the Task after expected WEO release dates or on a periodic cadence.
4. Send the dataset to Google Sheets, a webhook, cloud storage, or your warehouse.
5. Join on countryCode, indicatorCode, and year.
6. Retain edition and retrievedAt to compare revisions between runs.

The Actor emits snapshots. Diff two datasets in your downstream system to identify changed values or a newly extended forecast horizon.

Spreadsheet and data-pipeline exports

From the dataset page, use the Apify export controls for JSON, JSONL, CSV, Excel, XML, or RSS.

For stable warehouse loading:

• treat (countryCode, indicatorCode, year, edition) as a version-aware key;
• store value as a numeric column;
• retain unit because indicators use different scales;
• keep sourceUrl and sourceLastModified for lineage;
• do not assume every indicator has every country-year combination.

Run through the Apify API

Replace YOUR_TOKEN with an Apify API token.

cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~imf-world-economic-outlook-data/runs?token=YOUR_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{"indicators":["NGDP_RPCH"],"countries":["USA"],"startYear":2020,"endYear":2030,"maxItems":20}'

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/imf-world-economic-outlook-data').call({
  indicators: ['NGDP_RPCH', 'PCPIPCH'],
  countries: ['USA', 'DEU'],
  startYear: 2020,
  endYear: 2030,
  maxItems: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("automation-lab/imf-world-economic-outlook-data").call(run_input={
    "indicators": ["NGDP_RPCH", "PCPIPCH"],
    "countries": ["USA", "DEU"],
    "startYear": 2020,
    "endYear": 2030,
    "maxItems": 50,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

Use with Apify MCP

Add the Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/imf-world-economic-outlook-data"

Claude Desktop, Cursor, and VS Code setup

Desktop and editor clients can use this MCP configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/imf-world-economic-outlook-data"
    }
  }
}

Example prompts:

• “Export US and German GDP growth and inflation from 2019 through the current IMF forecast horizon.”
• “Get forecast-only debt-to-GDP observations for Brazil, India, Mexico, South Africa, and Türkiye.”
• “Run my saved WEO model-refresh Task and summarize which countries have the highest forecast inflation.”

Reliability and retry behavior

The Actor uses the official public IMF DataMapper JSON endpoints.

Each request has a 30-second timeout. Network failures, HTTP 429, and temporary server errors are retried up to three times with exponential backoff and jitter. Stable client errors, invalid metadata, and malformed responses fail the run.

There is no hidden browser or residential-proxy fallback. This keeps runs lightweight and makes cost behavior predictable.

Limits and data freshness

• Maximum 12 indicators, 50 countries, and 10,000 rows per run.
• Availability differs by country, indicator, and year.
• The latest IMF response is fetched on every run; the Actor does not maintain an independent economic database.
• IMF may revise historical values as well as forecasts.
• Country coverage follows the IMF countries metadata endpoint.
• Analytical groups and regions are not accepted as countries in this release.
• maxItems stops output in indicator, country, then ascending-year order.
• A valid selection with no values in the chosen period completes with an empty dataset.

Legality and responsible use

The Actor accesses public IMF data without authentication. Review IMF terms, attribution guidance, and applicable policies for your use case.

Economic statistics can be revised and should not be treated as personalized financial, legal, or investment advice. Preserve the source, edition, unit, and retrieval fields when publishing analysis. Do not misrepresent forecasts as observed outcomes.

Troubleshooting

Why did the run reject my indicator?

The code must exist in current IMF metadata and belong to the WEO dataset. Check spelling and use codes such as NGDP_RPCH, not a natural-language indicator name.

Why is my dataset empty?

The selected indicator-country combination may not contain values in the requested years, or the historical/forecast filter may exclude every value. Expand the year range or include both observation types.

Why are fewer rows returned than expected?

Check maxItems first. Also remember that IMF coverage is sparse for some indicators and countries.

Why is the edition or value different from an older export?

The Actor always reads current IMF metadata and values. IMF releases can revise both history and forecasts. Compare edition, sourceLastModified, and retrievedAt.

Does the Actor need a proxy?

No. It currently uses the official public JSON API directly. If the upstream API is temporarily unavailable, retry later rather than adding proxy settings.

FAQ

Does it download the entire WEO database?

No. It fetches selected DataMapper indicator series and emits only the requested countries, years, and period types.

Can I request country names instead of codes?

No. Use IMF country codes such as USA, DEU, or BRA. The output includes the country name.

Can I get forecasts only?

Yes. Set observationTypes to ["forecast"].

Can I monitor revisions?

Schedule repeated runs and diff version-aware keys in your own destination. The Actor provides the edition, source modification time, and retrieval time but does not send alerts itself.

Are null values exported?

Missing observations are skipped. Metadata fields that IMF does not supply, such as a unit or modification timestamp, can be null.

Is the output suitable for charts?

Yes. Group by country and indicator, sort by year, and use value as the numeric series. Keep units separate.

Related Actors

This Actor is intentionally standalone because the Automation Labs portfolio does not currently contain another IMF WEO exporter. For project-level development-finance research rather than macroeconomic observations, see World Bank Projects Scraper.

Support

For a reproducible issue, include the input, run URL, IMF indicator codes, country codes, and the unexpected field or year. Do not include API tokens or private downstream credentials.