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
Data+ license
With Data+ the only way to get the credentials for API's is by having the MB app installed in the same machine as the Python environment. See Technical information for the link.
Note that keyring or will only work with Web Api license credentials, it won't work if you have Data+.
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.
