Accessing IMF Data with imfidatar

This tutorial demonstrates how to interact with the IMF’s iData platform using the imfidatar package. The package wraps the underlying SDMX interface, simplifying authentication, dataset discovery, and data retrieval. Compared with the earlier wrapper functions we used, imfidatar exposes a more transparent interface while still hiding much of the complexity of SDMX queries.

We will walk through installation, exploring available datasets, constructing query keys, retrieving data (both public and restricted), and working with labelled results.

Pre-requisites

You first need to the install the rsdmx package. You cannot install it the usual way. You need to install the latest version from Github. Before you can install it, you first need to load (or install) the devtools package.

#install.packages("devtools") library(devtools)

You then can install the rsdmx package from Github. Please note the force=TRUE argument, which helps prevent installation problems.

install_github("opensdmx/rsdmx", force = TRUE)

Installation and Setup

The imfidatar package is hosted on GitHub rather than CRAN, so you need to install it from source. You must also install the latest version of rsdmx (which handles low‑level SDMX requests).

# Install remotes only once
# install.packages("remotes")
library(remotes)

# Install rsdmx from GitHub using devtools
# install.packages("devtools")
devtools::install_github("opensdmx/rsdmx", force = TRUE)

# Option 1: install imfidatar directly from GitHub (requires Git installed and typically does not work on Fund machines)
remotes::install_git('https://github.com/BasBBakkerIMF/imfidatar.git')

# Option 2: download the imfidatar source tarball and install locally
url <- "https://codeload.github.com/BasBBakkerIMF/imfidatar/tar.gz/HEAD"
tf  <- tempfile(fileext = ".tar.gz")
curl::curl_download(url, tf)
remotes::install_local(tf)

The imfidatar package exports an object named idata with three main components:

  • metadata – functions for exploring datasets and their dimensions;
  • retrieval – functions to download data;
  • utils – helper functions, such as for constructing keys.
# Load the package once installed
library(imfidatar)
imfidatar loaded.

Exploring available datasets

Before querying data you often need to know which datasets are available. imfidatar provides a helper to list all public datasets exposed via the IMF’s SDMX API:

# Show publicly available datasets
datasets <- idata$metadata$imfdata_show_datasets()
head(datasets)
       id agencyID
1 FSIBSIS  IMF.STA
2      FM  IMF.FAD
3     ITG  IMF.STA
4     EER  IMF.STA
5   IIPCC  IMF.STA
6 ITG_WCA  IMF.STA
                                                                                      Name.en
1 Financial Soundness Indicators (FSI), Balance Sheet, Income Statement and Memorandum Series
2                                                                         Fiscal Monitor (FM)
3                                                          International Trade in Goods (ITG)
4                                                               Effective Exchange Rate (EER)
5                       Currency Composition of the International Investment Position (IIPCC)
6                                  International Trade in Goods, World and Country Aggregates
  version  uri
1  18.0.0 <NA>
2   5.0.0 <NA>
3   4.0.0 <NA>
4   6.0.0 <NA>
5  13.0.0 <NA>
6   2.0.4 <NA>
                                                                         urn
1 urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:FSIBSIS(18.0.0)
2       urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.FAD:FM(5.0.0)
3      urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:ITG(4.0.0)
4      urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:EER(6.0.0)
5   urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:IIPCC(13.0.0)
6  urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:ITG_WCA(2.0.4)
  isExternalReference isFinal validFrom validTo dsdRef Name.fr Name.ar Name.es
1               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
2               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
3               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
4               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
5               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
6               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
  Name.pt Name.ja Name.zh Name.ru
1    <NA>    <NA>    <NA>    <NA>
2    <NA>    <NA>    <NA>    <NA>
3    <NA>    <NA>    <NA>    <NA>
4    <NA>    <NA>    <NA>    <NA>
5    <NA>    <NA>    <NA>    <NA>
6    <NA>    <NA>    <NA>    <NA>
# Show all datasets, including restricted ones (requires authentication)
datasets_auth <- idata$metadata$imfdata_show_datasets(needs_auth = T)
Using authorization_code flow
Loading cached token
Server did not provide a refresh token: you will have to reauthenticate to refresh.
Add the 'offline_access' scope to obtain a refresh token.
head(datasets_auth)
                         id    agencyID
1                   FSIBSIS     IMF.STA
2 WEO_LIVE_2024_APR_VINTAGE IMF.RES.WEO
3                        RE     IMF.STA
4                       ITG     IMF.STA
5                     IIPCC     IMF.STA
6                       SRD     IMF.RES
                                                                                      Name.en
1 Financial Soundness Indicators (FSI), Balance Sheet, Income Statement and Memorandum Series
2                                                                         WEO Live 2024 April
3                                                                       Renewable Energy (RE)
4                                                          International Trade in Goods (ITG)
5                       Currency Composition of the International Investment Position (IIPCC)
6                                                            Structural Reform Database (SRD)
  version  uri
1  18.0.0 <NA>
2   1.0.0 <NA>
3   1.0.1 <NA>
4   4.0.0 <NA>
5  13.0.0 <NA>
6   1.0.0 <NA>
                                                                                              urn
1                      urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:FSIBSIS(18.0.0)
2 urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.RES.WEO:WEO_LIVE_2024_APR_VINTAGE(1.0.0)
3                            urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:RE(1.0.1)
4                           urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:ITG(4.0.0)
5                        urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.STA:IIPCC(13.0.0)
6                           urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=IMF.RES:SRD(1.0.0)
  isExternalReference isFinal validFrom validTo dsdRef Name.fr Name.es Name.ar
1               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
2               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
3               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
4               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
5               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
6               FALSE    TRUE      <NA>    <NA>   <NA>    <NA>    <NA>    <NA>
  Name.pt Name.ja Name.zh Name.ru
1    <NA>    <NA>    <NA>    <NA>
2    <NA>    <NA>    <NA>    <NA>
3    <NA>    <NA>    <NA>    <NA>
4    <NA>    <NA>    <NA>    <NA>
5    <NA>    <NA>    <NA>    <NA>
6    <NA>    <NA>    <NA>    <NA>

The returned object is a data frame listing dataset identifiers. When you set needs_auth = TRUE, additional restricted datasets (those that require IMF credentials) will appear in the list. You will be prompted to log in when you first attempt to access those datasets.

Querying data by key

The core function for data retrieval is idata$retrieval$imfdata_by_key(). You must specify the dataset and a key that filters your request across different dimensions (e.g., countries, indicators, frequencies). The key can be provided either as a string (using + and . separators) or as a list. The following example pulls unemployment rates (LUR) and consumer prices (PCPI) from the World Economic Outlook (WEO) database for the United States and the Netherlands:

library(dplyr)

Attaching package: 'dplyr'
The following objects are masked from 'package:stats':

    filter, lag
The following objects are masked from 'package:base':

    intersect, setdiff, setequal, union
weodata <- idata$retrieval$imfdata_by_key(
  dataset = "IMF.RES:WEO",
  key     = "USA+NLD.LUR+PCPI.A"   # Countries (USA, NLD), indicators (LUR, PCPI), annual frequency
)
[rsdmx][INFO] Fetching 'https://api.imf.org/external/sdmx/2.1/data/IMF.RES,WEO/USA+NLD.LUR+PCPI.A/all/' 
# Select a few columns and inspect the tail of the data
weodata %>%
  select(COUNTRY, INDICATOR, TIME_PERIOD, value) %>%
  tail()
    COUNTRY INDICATOR TIME_PERIOD   value
199     USA      PCPI        2025 323.070
200     USA      PCPI        2026 331.035
201     USA      PCPI        2027 338.021
202     USA      PCPI        2028 345.307
203     USA      PCPI        2029 352.797
204     USA      PCPI        2030 360.470

Notice that dataset uses the prefix IMF.RES to indicate the department (Research, RES) combined with the dataset code (WEO). The key string is composed of dimensions separated by periods: countries (USA+NLD), indicators (LUR+PCPI), and frequency (A for annual).

Building a key programmatically

Constructing keys manually can be error‑prone, especially for datasets with many dimensions. The metadata component helps you discover dimension names and their valid values, and the utils component helps assemble a key in list form.

Retrieve dimension names

To see which dimensions a dataset exposes, call get_dimension_names() on its code:

# Get dimension names for the WEO dataset
dims <- idata$metadata$get_dimension_names("IMF.RES:WEO")
[rsdmx][INFO] Fetching 'https://api.imf.org/external/sdmx/2.1/datastructure/all/DSD_WEO/latest/?references=descendants' 
  Dimension
1   COUNTRY
2 INDICATOR
3      FREQ
print(dims)
  Dimension
1   COUNTRY
2 INDICATOR
3      FREQ

For WEO you will typically see COUNTRY, INDICATOR, and FREQ. More complex datasets have additional dimensions.

Explore dimension values

Use make_dimension_env() to create an environment containing all possible values for a given dimension. You can then reference values by their descriptive names. For example:

# Get environments for dimensions
countries   <- idata$metadata$make_dimension_env("IMF.RES:WEO", "COUNTRY")
indicators  <- idata$metadata$make_dimension_env("IMF.RES:WEO", "INDICATOR")
frequencies <- idata$metadata$make_dimension_env("IMF.RES:WEO", "FREQ")

# Inspect codes for specific labels
countries$`United States`                     # Country code for the United States
[1] "USA"
indicators$`Unemployment rate`                # Code for the unemployment rate series
[1] "LUR"
frequencies$Annual                            # Code for annual frequency
[1] "A"

Assemble and convert keys

After identifying the appropriate codes, you can assemble them into a list. Each element of the list should itself be a list when you have multiple selections for a given dimension. You can then convert that list into a key string using make_key_str(), though passing the list directly to imfdata_by_key() also works.

# Assemble key components
mycountries  <- list(countries$`Netherlands, The`, countries$`United States`)
myindicators <- list(
  indicators$`Unemployment rate`,
  indicators$`Gross domestic product (GDP), Constant prices, Domestic currency`
)
myfrequencies <- list(frequencies$Annual)

# Combine into a key list
mykey <- list(mycountries, myindicators, myfrequencies)

# Optional: build a key string from the list
mykeystr <- idata$utils$make_key_str(mykey)
print(mykeystr)
[1] "NLD+USA.LUR+NGDP_R.A"
# Fetch data using the list key
weo_data <- idata$retrieval$imfdata_by_key(
  dataset = "IMF.RES:WEO",
  key     = mykey
)
[rsdmx][INFO] Fetching 'https://api.imf.org/external/sdmx/2.1/data/IMF.RES,WEO/NLD+USA.LUR+NGDP_R.A/all/' 
weo_data %>%
  select(COUNTRY, INDICATOR, TIME_PERIOD, value) %>%
  tail()
    COUNTRY INDICATOR TIME_PERIOD        value
199     USA    NGDP_R        2025 2.373055e+13
200     USA    NGDP_R        2026 2.414443e+13
201     USA    NGDP_R        2027 2.462312e+13
202     USA    NGDP_R        2028 2.514551e+13
203     USA    NGDP_R        2029 2.567898e+13
204     USA    NGDP_R        2030 2.622377e+13

Using this approach ensures that your keys reflect valid codes and reduces the risk of misspelling a dimension value.

Accessing restricted data

Some datasets require authentication. When you attempt to access them, imfidatar uses your IMF login through Azure to request a token. To discover restricted datasets and their dimensions, first create a dataset environment with needs_auth = TRUE:

# Create an environment of all datasets (requires login)
mydatasets <- idata$metadata$make_dataset_env(needs_auth = TRUE)

# Select a specific dataset, e.g., the Bloomberg Data License
bloomberg <- mydatasets$`Bloomberg Data License `

# Check its dimensions
dims <- idata$metadata$get_dimension_names(bloomberg)
[rsdmx][INFO] Fetching 'https://api.imf.org/external/sdmx/2.1/datastructure/all/DSD_BBGDL/latest/?references=descendants' 
     Dimension
1       TICKER
2 MARKET_FIELD
3         FREQ
print(dims)
     Dimension
1       TICKER
2 MARKET_FIELD
3         FREQ
# Build dimension environments
tickers <- idata$metadata$make_dimension_env(dataset_or_db = bloomberg, dimension = "TICKER")
fields  <- idata$metadata$make_dimension_env(dataset_or_db = bloomberg, dimension = "MARKET_FIELD")
freqs   <- idata$metadata$make_dimension_env(dataset_or_db = bloomberg, dimension = "FREQ")

# Assemble a key for the Bloomberg dataset
bb_key <- list(
  c(tickers$`ALBANIAN LEK SPOT`),
  c(fields$`Ask Price`, fields$`Bid Price`),
  c(freqs$Daily)
)

# Fetch the data (requires authentication)
bb_data <- idata$retrieval$imfdata_by_key(
  dataset     = bloomberg,
  needs_auth  = TRUE,
  key         = bb_key,
  needs_labels = FALSE
)
[rsdmx][INFO] Fetching 'https://api.imf.org/external/sdmx/2.1/data/IMF.CSF,BBGDL/ALL_CURNCY.PX_ASK+PX_BID.D/all/' 
tail(bb_data)
          TICKER  FIELD FREQUENCY SCALE TIME_PERIOD OBS_VALUE value
14346 ALL_CURNCY PX_BID         D     0  2025-09-26     82.41 82.41
14347 ALL_CURNCY PX_BID         D     0  2025-09-29     82.21 82.21
14348 ALL_CURNCY PX_BID         D     0  2025-09-30     82.03 82.03
14349 ALL_CURNCY PX_BID         D     0  2025-10-01     82.02 82.02
14350 ALL_CURNCY PX_BID         D     0  2025-10-02     82.14 82.14
14351 ALL_CURNCY PX_BID         D     0  2025-10-03     82.06 82.06

If you are not already logged in, a browser window will open prompting you to enter your IMF credentials. Once authenticated, your token will be cached for subsequent requests.

Retrieving labelled data

For human‑readable outputs, set needs_labels = TRUE. This instructs imfidatar to include descriptive labels for each dimension in the returned data frame. The following example pulls balance of payments data (BOP) for several Central American countries and selects both the code and English label for the indicator:

library(dplyr)

keystr <- "CRI+HND+GTM+NIC+PAN+DOM+SLV.CD_T.S+SA+SB+SC+SD+SE+SF+SG+SH+SI+SJ+SK+SL.USD.A"

df <- idata$retrieval$imfdata_by_key(
  dataset      = "IMF.STA:BOP",
  needs_auth   = FALSE,
  key          = keystr,
  needs_labels = TRUE
)
[rsdmx][INFO] Fetching 'https://api.imf.org/external/sdmx/2.1/data/IMF.STA,BOP/CRI+HND+GTM+NIC+PAN+DOM+SLV.CD_T.S+SA+SB+SC+SD+SE+SF+SG+SH+SI+SJ+SK+SL.USD.A/all/' 
[rsdmx][INFO] Attempt to fetch DSD ref from dataflow description 
[rsdmx][INFO] Fetching 'https://api.imf.org/external/sdmx/2.1/dataflow/all/IMF.STA,BOP/latest/' 
[rsdmx][INFO] Fetching 'https://api.imf.org/external/sdmx/2.1/datastructure/all/DSD_BOP/latest/?references=descendants' 
[rsdmx][INFO] DSD fetched and associated to dataset! 
# Select columns with labels
df2 <- df %>%
  select(COUNTRY, INDICATOR, INDICATOR_label.en.label, TIME_PERIOD, value)
tail(df2)
     COUNTRY INDICATOR             INDICATOR_label.en.label TIME_PERIOD
3508     SLV        SL Government goods and services n.i.e.        2019
3509     SLV        SL Government goods and services n.i.e.        2020
3510     SLV        SL Government goods and services n.i.e.        2021
3511     SLV        SL Government goods and services n.i.e.        2022
3512     SLV        SL Government goods and services n.i.e.        2023
3513     SLV        SL Government goods and services n.i.e.        2024
         value
3508 109168831
3509 104664550
3510 128046584
3511 173681317
3512 167231356
3513 159268868

The resulting df2 includes an additional column INDICATOR_label.en.label containing an English description of each indicator. Similar language codes (e.g., .fr.label) are available for other languages.

Troubleshooting common errors

When calling imfdata_by_key(), you may encounter errors if the dataset identifier or key string is incorrect. For example, mis‑spelling the dataset (e.g., using WEO2 instead of WEO) will result in an error message. If your returned data appears to be missing expected columns such as TIME_PERIOD or value, double‑check that your key contains valid dimension codes and that you have included all required dimensions for the selected dataset.

imfidatar offers a flexible and powerful way to interact with IMF data via SDMX. By exploring metadata programmatically and constructing keys carefully, you can assemble complex queries without having to build URLs by hand.