• Overview
• References
• Introduction
  • Entities and metadata
  • Time series
  • The API
  • Authentication and authorization
  • Using the interactive reference documentation
  • Python wrapper
• Examples and use cases
  • Example of retrieving a time series in Python
  • Loading time series and entities
  • Revision history series
  • Searching for time series and entities
  • Creating and uploading in-house series

Overview

The Macrobond Data Web API feed gives access to the Macrobond database of time series and meta data. It is a REST Web API that uses JSON as the data format. OAuth2 is used for authentication and authorization.

The Macrobond Data Web API feed is a separately licensed solution.

This documentation refers to version 1 of the API and is subject to change.

References

Interactive documentation	https://api.macrobondfinancial.com/swagger
Documentation of metadata	https://help.macrobond.com/technical-information/common-metadata/
API URL	https://api.macrobondfinancial.com
OpenAPI definition	https://api.macrobondfinancial.com/swagger/v1/swagger.json
OAuth2 authentication	https://apiauth.macrobondfinancial.com/mbauth
OAuth2 token endpoint	https://apiauth.macrobondfinancial.com/mbauth/connect/token

Introduction

Entities and metadata

The Macrobond database contains objects called entities. Each entity has a set of metadata that describes the entity. There are different types of entities. The most common type is the time series. In
addition to the metadata, a time series also has a vector of values with corresponding dates. The Help page commonly used metadata also contains a useful introduction.

Each entity has a unique name. A name starts with one or more letters and can be followed by letters, digits and underscore. An entity can have more than one name. It can have a primary name and a list
of aliases. Any of these names can be used to reference the entity in, for example, a download operation.

The names do typically not have any special meaning. You should not infer any information from the name. For example, even though many names of time series begin with what looks like a country
code, like 'us', you should not use this to determine the country. Instead, you should use the metadata attribute called Region.

The metadata provides information about entities but can also be used as filters when search in the database.

Time series

A time series is an entity with a list of values and dates. The most important metadata of a time series are:

Frequency	The highest frequency is daily and the lowest annual.
DayMask	Used with daily series to tell what days of the week the series covers. It is a bitmask where but 1 is Sunday, 2 is Monday, 3 is Tuesday etc.
FullDescription	The title of the time series.
DisplayUnit	A text that gives the unit of the series.
Currency	The currency of the values
LastModifiedTimeStamp	The time when this entity was last modified. This includes changes to metadata as well as values. This can be used in some API calls (series/fetchseries and series/fetchvintageseries) to conditionally retrieve data only if it has changed. Note, this isn't available for calculated series because they are calculated on the fly when requested.

There is a date for each value in the time series. This date represents the period of the value and not when the value was sampled. For example, 2010-04-01 in a quarterly series represents 2010 Q2.

All dates indicated by the frequency are not always included. For example, for daily series January 1 might be missing since this was a public holiday.

A value might also be null, which indicates a missing value. Unlike the case when a date is missing, a missing value indicates that a value was expected for this date, but it is, for some reason, not available.

The API

The API is a REST based Web API over https that uses JSON as the data format. You can find detailed information about the parameters and data structures on the interactive documentation page.

Communication is made over https.

An Open API specification describes the API in a machine-readable format that can be used to generate stubs for most programming languages.

Authentication and authorization

The Macrobond Data Web API uses OAuth2 for authentication and authorization.

You use the Client credential grant flow to request an access token based on you client_id and client_secret. You need to specify a set scopes matching the API end-points you plan to use. In most
cases this includes 'macrobond_web_api.read_mb' to read time series and 'macrobond_web_api.search_mb' to be to search for series.

You can find information about the required scopes for each method in the documentation like this:
The access token is passed as a Bearer token in the Authorization http header in the subsequent API calls. The lifetime of a token is short (30-60 minutes). When you receive http status code 401 in the response from an API call, you need to request a new token and attempt the API call again. There are libraries for most programming platforms that helps with implementing OAuth2.

Note, the client_id and client_secrets are confidential information that must be stored in a safe way using best practices. It must not be shared.

Using the interactive reference documentation

The interactive reference documentation documents the arguments and data formats of the API methods.

It also allows you to test the methods directly on the web page. For this to work, you need to authorize first using the Authorize button in the top right corner. Fill in client_id and client_secrets and check the first scope called 'macrobond_web_api.read_mb'.

Once authorized you can test the methods. When the token expires, you will receive status 401 and you have to log out and log in again to get a new token.

Please note that some methods that return large amount of data can be slow for the web browser to handle.

Python wrapper

We have created The Macrobond Data API for Python (Python wrapper). The purpose of the Python API is to make the Data Web API easier to use in Python. For example, you do not need to bother with authentication, HTTP, JSON etc. and you get time series directly as Pandas series.

For documentation see The Macrobond Data API for Python (Python wrapper).
Find our guide and examples in Jupyter notebooks on Github.

Examples and use cases

The examples do not include examples of all API methods. See the reference documentation for a complete list.

Note that we have created The Macrobond Data API for Python (Python wrapper) to make Data Web API easier to use in Python. For documentation see The Macrobond Data API for Python (Python wrapper). Find our guide and examples in Jupyter notebooks on Github.

Example of retrieving a time series in Python

This example uses the Python package requests_oauthlib that can be installed using 'pip install requests_oauthlib'. It retrieves one series called 'usgdp' and prints the retrieved JSON data.

from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session
import json

# In a real-world case you should not include the credentials directly in the source code
client_id = user.test'
client_secret = 'somepassword'

token_url='https://apiauth.macrobondfinancial.com/mbauth/connect/token'
client = BackendApplicationClient(client_id=client_id, scope="macrobond_web_api.read_mb")
# To include access to methods for searching include an additional scope like
# scope="macrobond_web_api.read_mb macrobond_web_api.search_mb ")
mbapi = OAuth2Session(client=client)

# Helper method that will request new access token if required

def downloadMbApi(request):
  url = "https://api.macrobondfinancial.com/v1/" + request
  # This is typically the first time when we do not yet have a token
  if not mbapi.authorized:
    mbapi.fetch_token(token_url=token_url, client_id=client_id, client_secret=client_secret)
  r = mbapi.get(url)
  if r.status_code == 401:
    # If authorization failed, it is likely that the token has 
    expired. Get a new one and try again.
    mbapi.fetch_token(token_url=token_url, client_id=client_id, client_secret=client_secret)
    r = mbapi.get(url)
  r.raise_for_status()
  return r.content

# Use the helper method to access the API

d = downloadMbApi("series/fetchseries?n=usgdp")

jdata = json.loads(d)

print(jdata)

Loading time series and entities

GET series/fetchseries

Retrieve one or more time series.

The URL should not be longer than 2000 characters. Example:

Retrieve two time series.
series/fetchseries?n=usgdp&n=degdp
The result will be a list of series in the same order as requested.

POST series/fetchseries

Retrieve one or more time series.

The data is a list of series names to retrieve. Each name can optionally have a time stamp. If the series has not been modified since that time, the series will not be returned but instead there will be a status code indicating that it was not modified. The timestamp specified is typically the metadata LastModifiedTimeStamp from a previous response.

If you are retrieving many series, you might want to batch them into groups of 200 at a time for best efficiency. If your framework supports asynchronous requests, you might want to make two requests in parallel. Example:

To request two series, where one has a conditional timestamp.

[
  {
    "name": "usgdp",
    "ifModifiedSince": "2021-02-28T20:40:18.424Z"
  }
  {
    "name": "segdp"
  }
]

GET series/fetchentities

Retrieve one or more entities.

The URL should not be longer than 2000 characters. The result will be a list of sets of metadata in the same order as in the request. Example:

Get the metadata for a Release entity. The name of the Release was found as part of the metadata of the time series 'usgdp'. The metadata of the Release contains useful information such as the timestamp of the next expected release of new data.
series/fetchentities?n=rel_usbeana

GET seriestree/getleafseries

To get list of series from a particular location in the tree the path must be entered as found in the application, where each node is separated by a slash. Also, special characters should be encoded using RFC 2396. Example:

Retrieve series from Concept & Category/Prices/National Sources/Consumer Prices/Core CPI/Total/SA
seriestree/getleafseries?path=Concept%20%26%20Category%2FPrices%2FNational%20Sources%2FConsumer%20Prices%2FCore%20CPI%2FTotal%2FSA

Revision history series

For many series all changes to the values of the series are stored and they can be obtained as historical versions, or vintages, of the series. A change of an existing value or addition of a new value is regarded as a change of the series. With this information you can get older vintages of series, get point-in-time information when values where changed, get unrevised data or a specific revision. In the API there are several methods that allows you to obtain different views of this data.

GET series/getrevisioninfo

This method is used to find information related to revision history for one or more series:

• if revision history is maintained by Macrobond for this series
• how long history of revisions a series has
• a list of timestamps when changes were made of the values of the series

GET series/fetchvintageseries

Get the series with the values it had at some point in time.

The metadata RevisionTimestamp will contain the timestamp when the revision was recorded. Example:

Get the version of the series 'usgdp' with the values it had 1 January 2020.
series/fetchvintageseries?t=2020-01-01T00%3A00%3A00.100Z&getTimesOfChange=true&n=usgdp

GET series/fetchallvintageseries

Get all historical revision stored for a series.

You can optionally include a timestamp as a parameter to retrieve the series conditionally. This timestamp is typically the value of the metadata LastModifiedTimeStamp obtained from the previous request.

Note, this can be a large amount of data and the interactive documentation page can struggle to show the result.

Searching for time series and entities

Search for time series and other entities by using a filter based on metadata and optional text searching. The most common case is to search for time series and this is the default of no other entity types are specified. By default, the result contains the metadata of the found entities, but if you do not need this you can specify not to include it which will make the result smaller and faster to load.

Generate search code in Macrobond main app

When you input a query into search field in Macrobond’s Search tab, you can then generate a ready-to-use code for search in Web API Call:

GET search/entities

Example:

A common and powerful use case for searching is to use the RegionKey attribute. This attribute defines classifications of data that is available across regions. By inspecting the series 'usgdp', we can see that this series has RegionKey=gdp_total.

To search for series that are the corresponding series in the regions us, gb and se, you can use the following query:
search/entities?noMetaData=true&RegionKey=gdp_total&Region=us&Region=gb&Region=se

Side note: in the interactive documentation, you specify the filter part for this example like this:

{
  "RegionKey": "gdp_total",
  "Region": ["us", "gb","se"]
}

You can search for all series of this type for all regions:
search/entities?RegionKey=gdp_total
By prefixing a condition with '!' you can exclude matching series. This query will return the GDP series identified by Macrobond, but excludes those where we only have annual data:
search/entities?RegionKey=gdp_total&!Frequency=annual

POST search/entities

This method offers the same search capabilities as the 'GET search/entities' described above, but adds the option of specifying several sets of filters. These filters will be linked together based on the entity type. Example:

This query will look for all entities of type Company with a specific classification. It will then find all entities of type Security associated with those companies that also have the attribute CompanyKey=main_equity. Finally, a match will be made with all TimeSeries, the default type, associated with those securities and that have DataType=close.

The result will be all series with the closing price of the equity of companies of the specific classification.

{
  "filters":
  [
    {
      "entityTypes": ["Company"],
      "mustHaveValues": { "IcbClassification":"icb_2713" }
    },
    {
      "entityTypes": ["Security"],
      "mustHaveValues": { "CompanyKey":"main_equity" }
    },
    {
      "mustHaveValues": { "DataType":"close" }
    }
  ]
}

Creating and updating in-house series

You can create and update a limited set of in-house series using the API just as you can do using the Macrobond application.

To be able to use the API methods related to uploading series, you must request the scope macrobond_web_api.write_ih as part of the authentication.

GET seriestree/getseriesstoragelocations

Each in-house series is identified with a prefix like “ih:mb:priv:” followed by a name that starts with a lower case letter followed by lower case letter, digits and underscore. The prefix identifies the storage location. You can list the storage locations and the corresponding prefixes by calling the API method seriestree/getseriesstoragelocations.
The storage location dictates who can access the series. The most common storage locations are "priv", for private series that can only be access using the account that uploads them, and "com" that can be accessed by the whole company.

POST series/uploadseries

To create or update a series, you call series/uploadseries and post a JSON structure containing values and metadata. At a minimum you need to specify the metadata attributes PrimName, Description, Region, IHCategory and Frequency.
For more information about metadata, see Entities and metadata.

You can either specify a list of one timestamp per value, or specify the StartDate metadata attribute. For daily series, the DayMask attribute must also be included.

Here is an example of a payload that creates or updates a private series called "test".

{
   "values": [12.23, 45.56],
   "dates": ["2021-09-23", "2021-10-21"],
   "metadata": {
      "PrimName": "ih:mb:priv:test",
      "Description": "A test series",
      "Region": "us",
      "IHCategory": "Test",
      "Frequency": "monthly"
   }
}

The dates must be in ascending order.

If your series contains one observation for each per period, you can specify the StartDate instead of the array of dates.

{
   "values": [12.23, 45.56],
   "metadata": {
      "PrimName": "ih:mb:priv:test",
      "Description": "A test series",
      "Region": "us",
      "IHCategory": "Test",
      "Frequency": "monthly"
      "StartDate": "2021-09-23"
   }
}

The attribute IHCategory can be set to any text. This will be used in the Macrobond application user interface when organizing the series into groups.

GET seriestree/getusedinhousecategories

You can get a list of previously used values of IHCategory by calling seriestree/getusedinhousecategories.

DELETE series/deleteseries

In-house series can be deleted with a call to series/deleteseries.