imfapi

Installation

install.packages("imfapi")

Usage

library(imfapi)

The imfapi package provides a four-step workflow for retrieving data from the IMF’s SDMX API:

Step 1: List available dataflows and select one

Start by listing all available IMF datasets (dataflows) to find the one you need:

imf_get_dataflows() |>
  head() |>
  # Note: We use a custom helper function to truncate long strings in columns
  truncate_text(max_chars = 10) |>
  knitr::kable()

Choose a dataflow based on its id, name, and description. In this example, we’ll use the “PPI” (Producer Price Index) dataflow.

Step 2: Get the dimensions for filtering

Each dataflow has a datastructure that defines which dimensions you can filter on. Use imf_get_datastructure() to see what dimensions are available:

imf_get_datastructure(
  "PPI", include_time = TRUE, include_measures = TRUE
) |>
  knitr::kable()

The dimension_id column shows the filter dimensions you can use (e.g., COUNTRY, FREQUENCY). Set include_time = TRUE to see time dimensions and include_measures = TRUE to see measure dimensions.

Step 3: Fetch codelists for dimensions you want to filter on

For any dimension you want to filter, retrieve its codelist to see the valid codes you can use:

imf_get_codelists(dimension_ids = c("COUNTRY"), dataflow_id = "PPI") |>
  head() |>
  truncate_text(max_chars = 10) |>
  knitr::kable()

The code column shows the values you’ll use in your filters (e.g., “USA”, “CAN”). The name column provides human-readable labels. You can request codelists for multiple dimensions at once by passing a vector of dimension IDs.

Step 4: Request data with your filters

Finally, use imf_get() to fetch the actual data. Pass a named list of dimension filters where each name is a dimension_id and each value is a character vector of codes:

imf_get(
  dataflow_id = "PPI",
  dimensions = list(FREQUENCY = c("A"), COUNTRY = c("USA", "CAN"))
) |>
  head()

## # A tibble: 6 × 6
##   COUNTRY INDICATOR TYPE_OF_TRANSFORMATION FREQUENCY TIME_PERIOD OBS_VALUE
##   <chr>   <chr>     <chr>                  <chr>     <chr>           <dbl>
## 1 CAN     PPI       IX                     A         1956             15.8
## 2 CAN     PPI       IX                     A         1957             16.1
## 3 CAN     PPI       IX                     A         1958             16.2
## 4 CAN     PPI       IX                     A         1959             16.4
## 5 CAN     PPI       IX                     A         1960             16.4
## 6 CAN     PPI       IX                     A         1961             16.4

You can also use start_period and end_period arguments to filter by time (e.g., start_period = "2015", end_period = "2020"). If you omit a dimension from the dimensions list, all values for that dimension will be included.