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. 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 - 3.6.0 (Macrobond API 1.0.5). 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.


The Macrobond R API comes in the form of an R binary package called "MacrobondAPI" from the Macrobond repository at (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 = "")) 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="").

Upgrading the Macrobond API

  1. Restart R
  2. Run update.packages(repos="", 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.


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


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


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.


Here are a few examples:

# Load the library

# 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))

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


# Create a request of one or more series where the resulting time series will be converted to a common length and calendar. You can specify frequency, currency, date range, missing value and frequency conversion methods. You add series to this object by calling addSeries and you then pass this object to FetchTimeSeries in order to download the series.

seriesRequest <- CreateUnifiedTimeSeriesRequest()
setFrequency(seriesRequest, TimeSeriesFrequency[["Monthly"]])
addSeries(seriesRequest, "usgdp")
seriesExpressionCpi <- addSeries(seriesRequest, "uscpi")
setMissingValueMethod(seriesExpressionCpi, TimeSeriesMissingValueMethod[["None"]])
twoSeries <- FetchTimeSeries(seriesRequest)

# Add a series to a uniform series request. It returns a value of type SeriesExpression, which can be used to set further properties.
You need to do addSeries for each series. This allows you to access the settings object for each requested series.

If you happen to have your series in a list of some sort, it should be easy to call addSeries for each element in the list. If you find that you do this often, you can write a helper function that does this for you and also sets the conversion properties to what you need.


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


If you're having problems with the Macrobond R connector please contact us via 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:

and send us the output.