Download Data from the International Monetary Fund's Data API

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

CRAN Version Build Status CRAN Monthly Downloads CRAN Total Downloads

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.


Simple Country-Time-Variable

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.2979
## 2    CN 2014 118.9859
## 3    CN 2015 131.6297
## 4    GB 2013 105.7684
## 5    GB 2014 113.7014
## 6    GB 2015 121.7981

More complex data formats

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

Version 0.1.5

  • Warning on imf_ids that as of 2017-11-17 the request is unsuccessful.

Version 0.1.4

  • Resolved bug where imf_metadata produced malformed API calls. #9

  • Documentation improvements.

Version 0.1.3

  • Bug fix for IMF API call using default user agent to GET. Thanks to @cjyetman for fixing.

Version 0.1.2

  • 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.5 by Christopher Gandrud, 3 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