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. No AI models are used. This independent Automation Labs Actor is not affiliated with or endorsed by the IMF.

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 requests real GDP growth and inflation for the United States, Germany, and China, but its 20-row cap may stop before all countries or indicators. Output order is indicator, country, then ascending year. A cap is global, not per series. Keep the default for a small preview; use the complete example below for a multi-indicator snapshot.

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.
projectionStartYear	Source-declared indicator projection start year, or null if missing/invalid.
isProjection	Whether the year is at/after that source start; null when unknown. Not country-specific actual/forecast certification.
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.

Lookup catalogs and completion status

Every normal export saves supporting JSON artifacts in its run key-value store, linked from the Output tab:

• WEO_INDICATORS: WEO-only codes, labels, definitions, units, source edition, projection start and modification metadata.
• COUNTRIES: official country codes and labels, not analytical groups.
• RUN_SUMMARY: normalized requested selection, effective bounds, saved/charged observation counts, fetched/completely processed/partially processed/unprocessed indicators, status, stop reason and an empty-result explanation where known.

Catalogs reuse the two metadata requests already required by exports; they are not billable dataset records or a separate catalog-only mode. Available catalogs are saved before unknown codes are rejected. Official lookups: indicators, countries.

completed means all selected series were inspected. maxItems or chargeLimit warns that the selection may be incomplete; it does not assert more rows exist or claim an exact eligible total. Unvisited indicators are not called missing. A valid 2099–2100 selection can legitimately complete empty, while upstream/validation/write errors remain failures. Summaries are best-effort on failure; pre-validation/startup failure may occur before a summary is available.

The source-declared projection fields come from the same v2 series response as its values and edition. Only a numeric whole year in 1980–2100 is accepted; absent/invalid metadata yields two nulls. observationType and its filters retain the edition-year convenience rule even if the source projection year differs. Neither classification certifies a country-specific IMF actual.

Example input

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

Save this input as a Task for a complete two-indicator, three-country, nine-year snapshot: up to 54 rows when source cells exist. The explicit maxItems: 100 is sufficient; the default 20 is intentionally only a preview.

Example output

Illustrative output shape (values and edition are not a current economic assertion):

{
  "countryCode": "USA",
  "countryName": "United States",
  "indicatorCode": "NGDP_RPCH",
  "indicatorName": "Real GDP growth",
  "unit": "Annual percent change",
  "year": 2022,
  "value": 2.5,
  "observationType": "historical",
  "projectionStartYear": 2026,
  "isProjection": false,
  "edition": "April 2026",
  "dataset": "WEO",
  "sourceUrl": "https://www.imf.org/external/datamapper/api/v2/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.

On platform pay-per-event runs, the Actor charges the start event after validating selections. If that event is unaffordable, no series is fetched or observation saved. It charges observation batches of at most 500 and saves only the exact successfully charged prefix, stopping when no further observation fits. The summary distinguishes chargeLimit from maxItems. Catalogs, summaries, invalid selections and missing values do not incur observation charges. Local/non-PPE execution still emits useful rows without requiring a nonzero charge receipt.

Charging precedes dataset writes. If a write fails after charging, the run fails and RUN_SUMMARY can show charged rows exceeding saved rows; it never presents those rows as successfully exported.

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 and at most three attempts total. Network failures, HTTP 429, and temporary server errors use exponential backoff and jitter. Stable client errors, non-JSON/malformed responses and invalid metadata fail without retrying deterministic response errors. Exhausted upstream failures remain failed runs, not successful empty exports.

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.

Sanitized diagnostics

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL query strings are removed; reports are retained for 30 days. Public source metadata and observations remain in your Apify run storage under your account retention/deletion settings; this Actor has no cross-run cache. Delete run datasets/KV records through Apify controls. The public IMF API receives only fixed catalog paths and validated indicator codes, not your country/year selection or credentials. Apify hosts run storage and execution; the private self-hosted GlitchTip service receives sanitized failure diagnostics, not economic-model output or AI training data. Normal operational logs contain bounded request attempts/status/elapsed time, fetched indicator count, saved/charged row counts and stop reason, not raw response payloads or secrets.

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.