Getting started with readimf

readimf provides tidy access to International Monetary Fund data through the new IMF SDMX 3.0 API at https://data.imf.org. This vignette shows the main workflows. The live calls are shown but not executed here, so that the vignette builds without a network connection.

The World Economic Outlook

The WEO is open and needs no key. Indicator and country codes are passed directly.

# Real GDP growth for the UK and US, 2018 to 2024
imf_weo("NGDP_RPCH", country = c("GBR", "USA"), start = 2018, end = 2024)

You can request a specific historical release for forecast evaluation:

imf_weo("NGDP_RPCH", country = "GBR", vintage = "2025-10")

Migrating from imfr: where did IFS go?

When the IMF retired International Financial Statistics it split the series across thematic data flows with no official crosswalk. imf_ifs() accepts the old IFS codes and routes them to their new homes. The supported series and their destinations are shown by imf_ifs_map():

imf_ifs_map()
#>             ifs_code                                              description
#> 1            PCPI_IX                          Consumer price index, all items
#> 2            PCPIPCH    Consumer price inflation, year-on-year percent change
#> 3  ENDA_XDC_USD_RATE Exchange rate, domestic currency per USD, period average
#> 4  ENDE_XDC_USD_RATE  Exchange rate, domestic currency per USD, end of period
#> 5           FPOLM_PA              Central bank policy rate, percent per annum
#> 6            FIMM_PA                     Money market rate, percent per annum
#> 7            FIDR_PA                          Deposit rate, percent per annum
#> 8            FILR_PA                          Lending rate, percent per annum
#> 9           RAFA_USD                Total reserves excluding gold, US dollars
#> 10            AIP_IX                              Industrial production index
#> 11            LUR_PT                               Unemployment rate, percent
#>     agency dataflow                          key_template default_freq
#> 1  IMF.STA      CPI            {country}.CPI._T.IX.{freq}            M
#> 2  IMF.STA      CPI {country}.CPI._T.YOY_PCH_PA_PT.{freq}            M
#> 3  IMF.STA       ER        {country}.XDC_USD.PA_RT.{freq}            M
#> 4  IMF.STA       ER       {country}.XDC_USD.EOP_RT.{freq}            M
#> 5  IMF.STA   MFS_IR    {country}.MFS166_RT_PT_A_PT.{freq}            M
#> 6  IMF.STA   MFS_IR      {country}.MMRT_RT_PT_A_PT.{freq}            M
#> 7  IMF.STA   MFS_IR    {country}.MFS135_RT_PT_A_PT.{freq}            M
#> 8  IMF.STA   MFS_IR    {country}.MFS162_RT_PT_A_PT.{freq}            M
#> 9  IMF.STA       IL       {country}.RXF11_REVS.USD.{freq}            M
#> 10 IMF.STA       PI               {country}.IND.IX.{freq}            M
#> 11 IMF.STA       LS                 {country}.U.PT.{freq}            M

So a request for the UK consumer price index, formerly PCPI_IX, becomes:

imf_ifs("PCPI_IX", country = "GBR", start = 2015)

Country coverage in the new data flows varies, especially for interest rates. If a country returns nothing, try another.

Discovering data

Browse the full catalogue, search it, and inspect a data flow’s key structure:

imf_dataflows()                 # the full catalogue
imf_search("balance of payments")
imf_dimensions("CPI")           # the dimension order for building a key
imf_codelist("CL_WEO_INDICATOR", agency = "IMF.RES")

Anything in the catalogue can be fetched with imf_data() by supplying a key in the dimension order reported by imf_dimensions():

imf_data("CPI", key = "GBR.CPI._T.IX.M", start = 2020)

Named database wrappers

Common databases have named wrappers that set sensible defaults:

imf_cpi("GBR", measure = "inflation")
imf_dots("USA", "GBR", flow = "exports")
imf_cofer(currency = "USD", measure = "share")
imf_commodity("POILWTI", measure = "usd")
imf_gfs("GBR", indicator = "revenue")

Getting started with readimf

The World Economic Outlook

Migrating from imfr: where did IFS go?

Discovering data

Named database wrappers

API keys