imf_dataset: Download a data series from the IMF

In christophergandrud/imfr: Download Data from the International Monetary Fund's Data API

Download a data series from the IMF

Description

Function to request data from a database through the IMF API endpoint.

Usage

imf_dataset(
  database_id,
  parameters,
  start_year,
  end_year,
  return_raw = FALSE,
  print_url = FALSE,
  times = 3,
  include_metadata = FALSE,
  accounting_entry,
  activity,
  adjustment,
  age,
  classification,
  cofog_function,
  commodity,
  comp_method,
  composite_breakdown,
  counterpart_area,
  counterpart_sector,
  currency_denom,
  cust_breakdown,
  disability_status,
  education_lev,
  expenditure,
  financial_institution,
  flow_stock_entry,
  freq,
  functional_cat,
  gfs_sto,
  income_wealth_quantile,
  indicator,
  instr_asset,
  instrument_and_assets_classification,
  int_acc_item,
  maturity,
  occupation,
  prices,
  product,
  ref_area,
  ref_sector,
  reporting_type,
  series,
  sex,
  sto,
  summary_statistics,
  survey,
  transformation,
  type,
  unit_measure,
  urbanisation,
  valuation
)

Arguments

database_id	character string. Database ID for database from which you would like to request data. Can be found using imf_databases.
parameters	list of data frames providing input parameters for your API request. Retrieve list of all possible input parameters using imf_parameters and filter each data frame in the list to reduce it to the inputs you want.
start_year	integer four-digit year. Earliest year for which you would like to request data.
end_year	integer four-digit year. Latest year for which you would like to request data.
return_raw	logical. Whether to return the raw list returned by the API instead of a cleaned-up data frame. This argument exists strictly for purposes of backward compatibility with earlier versions of imfr and will be discontinued in a future version.
print_url	logical. Whether to print the URL used in the API call.
times	numeric. Maximum number of requests to attempt.
include_metadata	logical. Whether to return the database metadata header along with the data series.
accounting_entry, activity, adjustment, age, classification, cofog_function, commodity, comp_method, composite_breakdown, counterpart_area, counterpart_sector, currency_denom, cust_breakdown, disability_status, education_lev, expenditure, financial_institution, flow_stock_entry, freq, functional_cat, gfs_sto, income_wealth_quantile, indicator, instr_asset, instrument_and_assets_classification, int_acc_item, maturity, occupation, prices, product, ref_area, ref_sector, reporting_type, series, sex, sto, summary_statistics, survey, transformation, type, unit_measure, urbanisation, valuation	character vector. Use imf_parameters to identify which parameters to use for requests from a given database and to see all valid input codes for each parameter.

Details

Only the database_id argument is strictly required; all other arguments are optional. If you provide a database_id without any other arguments, the function will attempt to download the entire database. However, many databases available through the API are too large to download in their entirety, and your request will fail. Additional arguments to the function act as filter parameters to reduce the size of the returned dataset. For instance, supplying c("A","M") as the freq argument will return all database observations of annual or monthly frequency, while excluding all observations of quarterly frequency.

There are two ways to supply parameters for your API request. The optimal way is to retrieve a list of data frames using imf_parameters, filter each data frame to retain only the parameters you want, and then supply the modified list object to imf_dataset as its parameters argument. However, users who are not comfortable modifying data frames in a nested list may find it easier to instead supply one or more character vectors as arguments, as in the example in the previous paragraph. (There are a total of 44 possible parameters for making request from various databases through the API, and each parameter uses unique input codes, which is why the parameters list method simplifies things!) These two methods for specifying parameters may not be combined. Only database_id, start_year, end_year, print_url, and times arguments may be used in combination with a parameters list object; any other arguments will be ignored (and a warning thrown).

Value

If return_raw == FALSE and include_metadata == FALSE, returns a tidy data frame with the data series. If return_raw == FALSE but include_metadata == TRUE, returns a list whose first item is the database header, and whose second item is the tidy data frame. If return_raw == TRUE, returns the raw JSON fetched from the API endpoint.

Examples

# Retrieve "Current Account, Goods and Services, Services, Travel, Personal,
# Other, Credit, US Dollars" for "United States" from the Balance of Payments
# database using the character vector method
df <- imf_dataset(database_id = 'BOP',freq='A',ref_area = 'US',
                  indicator = 'BXSTVPO_BP6_USD',start_year=2020)

christophergandrud/imfr documentation built on April 18, 2023, 11:25 a.m.