The Macrobond API for R

Introduction

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.

Requirements

The API requires Macrobond 1.16.26 or later to be installed and functioning on the computer where R is run. We have now tested with R 3.2.2, R 3.4.0 and 3.3.1 (Macrobond API 1.0.3) as well as R 3.5.0 (Macrobond API 1.0.4). 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.18 and Macrobond API for R version 1.0-3 and 1.0-4.

Installation

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

  1. Restart R
  2. 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").
  3. Install the MacrobondAPI package by running install.packages("MacrobondAPI", type="win.binary", repos="https://macrobond.net/appupdates/R").

Upgrading the Macrobond API

  1. Restart R
  2. Run update.packages(repos="https://macrobond.net/appupdates/R", type="win.binary").

We urge you to keep your Macrobond API for R up to date. We also suggest that you periodically upgrade the Macrobond application as described here.

Documentation

Once you have installed the Macrobond API package, you can view the documentation from R like this:

library(MacrobondAPI)
?MacrobondAPI

You can view documentation for a specific function directly like this:

?getValues

While using help available directly from within R - as described above - is the recommended way of reading the Macrobond R API documentation, you can also view the online.

Examples

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
if (getIsError(seriesGdp))
 stop(getErrorMessage(seriesGdp))

# Show a summary of the series object (same as "show(seriesGdp)")
seriesGdp

# Show the title
getTitle(seriesGdp)

# Get the values and dates
vectorOfValues <- getValues(seriesGdp)
vectorOfObservationDates <- getDatesAtStartOfPeriod(seriesGdp)

# Make a simple plot of the series
plot(seriesGdp)

# 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))
UploadOneOrMoreTimeSeries(seriesNew)

# 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")
if (!is.null(releaseGdpName))
{
 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.
 getFirstMetadataValue(getMetadata(releaseGdp), "NextReleaseEventTime")
}

License

The Macrobond R API uses the license GPL-2. It uses portions of an enhanced version of RDCOMClient. There is a source package available.

Troubleshooting

If you're having problems with the Macrobond R connector please contact us via https://www.macrobond.com/contact/support/ and:

  • Describe what you’re trying to achieve
  • Include the relevant code you tried to run
  • Provide information about version of Macrobond, R and the Macrobond’s R add–in. To do it, issue those two commands:
library(MacrobondAPI)
sessionInfo()

and send us the output.