The Macrobond API for R
Macrobond offers an API that can be used in R for Windows.
- Download any time series including values, dates and metadata.
- Convert a set of time series to a common calendar and optionally a common currency.
- Fill in missing values with a selection of methods.
- Upload your own series to the in-house database which can then be used in the Macrobond application and optionally shared with others.
The API requires Macrobond 1.16.26 or later to be installed and functioning on the computer where R is run. The Macrobond API has been tested with R 3.4.0, R 3.2.2 and 3.3.1 of the distributions from CRAN and MRAN. If you are running the 64-bit version of R, you need to use the 64-bit version of Macrobond.
The Macrobond API uses the "xts" package and requires version 0.9-7 of that package.
NB! We test that the API works with R.exe and RGui.exe. When R is used as an embedded component in other programs, it might or might not work. You need to test this yourself and we can only give limited support in those cases.
This document refers to Macrobond application version 1.16.26 and Macrobond API for R version 1.0-1.
The Macrobond R API comes in the form of an R binary package called "MacrobondAPI" from the Macrobond repository at https://macrobond.net/appupdates/R (you cannot browse to that URL). Here are two ways to install the Macrobond API package.
Method 1: Add the Macrobond repository to the list of repositories
You can add this repository to the list of repositories that R will search in various ways. On option is to use the command setRepositories(addURLs = c(Macrobond = "https://macrobond.net/appupdates/R")) or add the repository to the configuration file. See ?setRepositories for details. Once you have added the Macrobond repository to your list of repositories, you can just run this R command:install.packages("MacrobondAPI", type="win.binary")
Method 2: Explicitly specify the repository
- Restart R
- If you do not have "xts" installed, install it by install.packages("xts"). If you have "xts" installed, make sure you have the latest version by running update.packages("xts").
- Install the MacrobondAPI package by running install.packages("MacrobondAPI", type="win.binary", repos="https://macrobond.net/appupdates/R").
Upgrading the Macrobond API
- Restart R
- Run update.packages(repos="https://macrobond.net/appupdates/R", type="win.binary").
Once you have installed the Macrobond API package, you can view the documentation from R like this:library(MacrobondAPI)
You can view documentation for a specific function directly like this:?getValues
Here are a few examples:# Load the library library(MacrobondAPI) # Load the series "usgdp". If you want to load several series you can use "FetchTimeSeries(listOfSeriesNames)" instead.
seriesGdp <- FetchOneTimeSeries("usgdp")
# Check that the series loaded OK
# Show a summary of the series object (same as "show(seriesGdp)")
# Show the title
# Get the values and dates
vectorOfValues <- getValues(seriesGdp)
vectorOfObservationDates <- getDatesAtStartOfPeriod(seriesGdp)
# Make a simple plot of the series
# Get the currency of the series
metaGdp <- getMetadata(seriesGdp)
currency <- getFirstMetadataValue(metaGdp, "Currency")
# Convert the Macrobond time series object to an xts series
seriesGdp.xts <- as.xts(seriesGdp)
# Upload an in-house time series
seriesNew = CreateTimeSeriesObject("ih:mb:priv:s1", "My forecast", "us", "Forecasts", "Monthly", as.Date("1990-01-01"), c(12.2, 12.7, 12.8, 13.0))
# Get information about a release.
# The name of the release is a metadata property of the time series.
# The release has a corresponding "entity" in the database.
releaseGdpName <- getFirstMetadataValue(metaGdp, "Release")
releaseGdp <- FetchOneEntity(releaseGdpName)
# The NextReleaseEventTime attribute contains information about the next scheduled release of updated series.
# The date might be missing if no release date is known.