Skip to contents

Getting started with IMF SDMX 3.0 data

Source: vignettes/getting-started.Rmd
getting-started.Rmd

imf.data follows a four-step workflow: find a dataflow, inspect its dimensions, inspect valid values, and download observations.

Find a dataflow 

library(imf.data)

datasets <- list_datasets("IMF.STA")
datasets[datasets$id == "CPI", ]

Dataflows are identified by an agency, ID, and version. Most examples in this guide use the IMF Statistics Department agency, IMF.STA.

Inspect dimensions 

dimensions <- list_dimensions("CPI")
dimensions

The returned order is the order used by an SDMX series key. For the higher-level workflow, use dimension names in a named filters list instead of assembling a positional key.

Inspect available values 

list_dimension_values(
  "CPI",
  "FREQUENCY",
  filters = list(COUNTRY = "USA")
)

Availability is conditional. Adding filters for other dimensions narrows the codes returned for the requested dimension.

Download observations 

cpi <- get_data(
  "CPI",
  filters = list(
    COUNTRY = c("USA", "CAN"),
    INDEX_TYPE = "CPI",
    COICOP_1999 = "_T",
    TYPE_OF_TRANSFORMATION = "IX",
    FREQUENCY = "M"
  ),
  start_period = "2020",
  last_n_obs = 12,
  attributes = c("SCALE", "STATUS")
)
cpi

The result contains one row per observation. SDMX dimensions and TIME_PERIOD are character columns, while OBS_VALUE is numeric.

Use first_n_obs or last_n_obs to limit observations per matching series. The two arguments cannot be combined.

Reshape for comparison

get_data() returns one row per observation, which is convenient for plotting and analysis but awkward for comparing countries side by side. Reshape it to one column per country with base R:

wide <- reshape(
  cpi[c("COUNTRY", "TIME_PERIOD", "OBS_VALUE")],
  idvar = "TIME_PERIOD",
  timevar = "COUNTRY",
  direction = "wide"
)
wide[order(wide$TIME_PERIOD), ]

Handle validation errors

get_data() and the raw sdmx_*() functions validate their arguments before contacting the API, so mistakes raise an informative error instead of an opaque HTTP failure:

tryCatch(
  get_data(
    "CPI",
    filters = list(COUNTRY = "USA"),
    first_n_obs = 1,
    last_n_obs = 1
  ),
  error = function(e) conditionMessage(e)
)

Use list_dimension_values() to confirm a code is valid for the current dataflow before retrying.

Use the raw API

The raw functions preserve the complete nested SDMX response:

raw <- sdmx_data(
  "CPI",
  key = "USA.CPI._T.IX.M",
  last_n_obs = 2
)

availability <- sdmx_availability(
  "CPI",
  component_id = "FREQUENCY",
  filters = list(COUNTRY = "USA"),
  mode = "available"
)

metadata <- sdmx_metadata(detail = "allstubs")

Raw JSON responses are unsimplified lists so their zero-based SDMX indexes can be decoded without losing structure. XML responses are available as text by setting format = "xml".

Configure a proxy

httr2 automatically respects standard environment variables such as HTTPS_PROXY, HTTP_PROXY, and NO_PROXY. To configure a proxy only for imf.data, use:

set_imf_proxy(
  "http://proxy.example.com",
  port = 8080,
  username = Sys.getenv("PROXY_USER"),
  password = Sys.getenv("PROXY_PASSWORD")
)

This configuration applies to every package request in the current R session. Remove it with:

Keep credentials in environment variables or another secrets manager rather than writing them directly into scripts.