Download Data from the International Monetary Fund's Data API

Explore and download data from the International Monetary Fund's data API <>.

R package for interacting with the International Monetary Funds's RESTful JSON API.

You can use the imf_data function to download the data the IMF makes available via its API. To do this you will need at least the following information:

  • database_id: the ID of the specific database you wish to download the data series from. You can find the list of IDs and their description using the imf_ids function.

  • indicator: the IMF indicators of the variables you want to download. One way to find these is to:

    1. Use the database_id for the database you want to access with the imf_codelist function to find the code list of the database.

    2. Then using the indicator code (usually CL_INDICATOR_database_id) in imf_codes, you can find the data series indicator codes in that database.

    Tip: if you have a number of country identifiers that are not in ISO2C format, you can use the helpful countrycode package to convert them.

  • country: one or more ISO two letter country codes for the countries you would like to download the data for. If country = 'all' then all available countries will be downloaded.

  • start and end: the start and end years for which you would like to download the data.

  • freq: the frequency of the series you want to download. Often series are available annually, quarterly, and monthly.

Imagine that we want to download Effective Exchange Rate (CPI base) for China and the UK for 2013:

real_ex <- imf_data(database_id = 'IFS', indicator = 'EREER_IX',
                    country = c('CN', 'GB'), freq = 'A',
                    start = 2013, end = current_year())
##   iso2c year EREER_IX
## 1    CN 2013 115.2938
## 2    GB 2013 105.7680

While many quantities of interest from the IMF database are in simple country-time-variable format, many are not. For example, Direction of Trade Statistics include country-year-variable and a "counterpart area". By default, imf_data would only return the first, but not the last.

Because of the many possible data structures available from the imf, imf_data allows you to return the entire API call as a list. From this list you can then extract the requested data. To do this use the return_raw = TRUE argument, e.g.:

data_list <- imf_data(database_id = "DOT", indicator = "TXG_FOB_USD", 
                      country = "US", return_raw = TRUE)

Then extract the data series (it is typically contained in CompactData$DataSet$Series):

data_df <- data_list$CompactData$DataSet$Series
## [1] "@FREQ"             "@REF_AREA"         "@INDICATOR"       
## [4] "@COUNTERPART_AREA" "@UNIT_MULT"        "@TIME_FORMAT"     
## [7] "Obs"

You can then subset and clean up data_df to suit your purposes.


All updates will be detailed here

  • Fixed a bug preventing imf_data from successfully completing return_raw = TRUE.

  • Added new internal function current_year so that the current year is the default end year. Thanks to Jay Ulfelder for inspiration.

  • Minor documentation typo fix.

## Version 0.1.1

  • Updated URL GET request schema to meet changes introduced by the IMF on 2016-07-27. These changes had broke imf_data, but the issue is now resolved. For more details on the API changes see:

  • imf_data now has an optional argument (print_url) that will print to the URL used in the API to the console. This can be useful for API debugging.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.1.4 by Christopher Gandrud, 6 months ago

Report a bug at

Browse source code at

Authors: Christopher Gandrud [aut, cre]

Documentation:   PDF Manual  

GPL (>= 3) license

Imports dplyr, httr, jsonlite

See at CRAN