databank.fromIMF.data
Download databank of time series from IMF Data Portal
Syntax for plain vanilla requests (most datasets)
[outputDb, info] = databank.fromIMF.data(dataset, frequency, areas, indicators, ...)
Syntax for requests that need more dimensions
[outputDb, info] = databank.fromIMF.data(dataset, frequency, areas, dimensions, ...)
Input Arguments
dataset
[ string ]
IMF dataset ID; only one dataset is allowed in one data request.
frequency
[ Frequency ]
Date frequency for the output time series; the
frequency
must be yearly, quarterly or monthly; only one frequency is allowed in one data request.
areas
[ string ]
List of reference areas for which the output time series will be retrieved; an empty string or emtpy array means all reference areas.
indicators
[ string ]
List of indicators that will be retrieved for each of the
areas
.
dimensions
[ cell ]
Cell array of string arrays; each element of the cell array stands for one particular dimension that needs to be specified in the request (depending on the dataset).
counter=empty
[ string ]
List of counterparty reference areas for which the output time series will be retrieved; counterparty reference areas are needed for only some of the IMF databanks, such as Directions of Trade Statistics (DOT); an empty string or empty array means all counterparty reference areas.
Output arguments
outputDb
[ struct | Dictionary ]
Output databank with time series retrieved from an IMF databank.
info
[ struct ]
Output information struct with the following fields:
.Request
- the entire request string (including the URL)
.Response
- a JSON struct with the IMF data portal response
Options for HTTP Request
EndDate=-Inf
[ Dater ]
End date for the data requested;
-Inf
means the date of the latest observation for each series.
StartDate=-Inf
[ Dater ]
Start date for the data requested;
-Inf
means the date of the earliest observation for each series.
URL="http://dataservices.imf.org/REST/SDMX_JSON.svc/CompactData/"
[ string ]
URL for the IMF data portal HTTP request.
WebOptions=weboptions("Timeout", 9999)
[ weboption ]
A weboptions object with HTTP settings.
WhenEmpty="warning"
[ "error"
| "warning"
]
How to report an empty response from the server:
"error"
means an error is thrown and the execution of the function stops;
"warning"
means a warning is thrown and an empty databank is return without interrupting the execution of the function.
Options for output databank
AddToDatabank=struct()
[ struct | Dictionary ]
Add the output time series to this databank.
ApplyMultiplier=true
[ true
| false
]
Apply the unit multiplier to the output time series data, scaling them to basic units (e.g. from millions).
Options for output time series names
NameFunc=[]
[ empty | function_handle ]
Function that will be applied to each time series name before it is stored in the
outputDb
.
IncludeArea=true
[ true
| false
]
Include the respective reference area code as a prefix in the name of each output time series.
IncludeCounter=true
[ true
| false
]
Three-dimensional requests only (with counterparty reference area): Include the respective counterparty reference area code as a suffix in the name of each output time series.
Separator="_"
[ string ]
Separator used in the area prefix and/or the counterparty area suffix in the output time series names.
Description
This function returns a databank of time series from the IMF data portal. To create a data request, you need to know the IMF dataset code, the reference area code(s), the indicator code(s), and for three-dimensional requests, also the counterparty reference area code(s).
Leaving the reference area code, the indicator code or the counterparty reference area code empty will return data for all of those that exist in that dimension.
The IMF data portal has bandwith restrictions. Sometimes, requests returning larger amounts of data need to be split into smaller, more specific requests. Sometimes, the function needs to be called several times before an actual data response is returned.
Examples
Plain vanilla three-dimensional requests
Most of the IMF datasets need three dimensions to be specified:
- date frequency (only one single date frequency can be specified)
- reference area(s)
- indicator(s)
From the IMF IFS dataset, retrieve quarterly nominal GDP in localy currency for the US:
d = databank.fromIMF.data("IFS", Frequency.QUARTERLY, "US", "NGDP_XDC")
Retrieve nominal GDP in localy currency for all areas (countries and regions) for which this indicator is available:
d = databank.fromIMF.data("IFS", Frequency.QUARTERLY, [], "NGDP_XDC")
Retrieve all indicators available from the IMF IFS databank for the US; do not include the country prefix (here, "US_") in the names of the output time series:
d = databank.fromIMF.data("IFS", Frequency.QUARTERLY, "US", [], "includeArea", false)
Multi-dimensional requests
Some IMF datasets require some extra dimensions; for instance, the IMF
Directions of Trade Statistics dataset (code DOT
) needs an extra
dimension for the counterparty following after the indicator dimension; the
IMF Government Finance Statistics - Main Aggregates and Balances dataset
(code GFSMAB
) needs a government sector dimension and a unit of
measurement dimension, both preceding the indicator dimension.
Retrieve yearly exports from US (code US
) to Euro Area (code U2
):
d = databank.fromIMF.data("DOT", Frequency.YEARLY, "US", {"TXG_FOB_USD", "U2"});
From the IMF DOT databank (Directions of Trade Statistics), retrieve yearly exports from US to all reported areas:
d = databank.fromIMF.data("DOT", Frequency.YEARLY, "US", "TXG_FOB_USD", []);