Introduction

Macrobond offers an API that can be used in R for Windows.

Requirements

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.

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").

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

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.