Package macrobond_data_api the Macrobond Data API for Python

The Macrobond Data API for Python is used to access the world’s most extensive macroeconomic, aggregate financial and sector database provided by Macrobond. Exposes a common API in Python for the Macrobond Web and Client data APIs

You have to be a licensed user and have a Data+ or data feed user account in order to use the API.

Installing macrobond-data-api and Supported Versions

Supported versions of Python are currently 3.8+.

The package is available at PiPy and can be installed using this command:

python -m pip install macrobond-data-api

Using of system keyring for http proxy

For users operating behind an HTTP proxy, it is advisable to utilize the system keyring to store proxy settings and credentials. This can be conveniently accomplished by executing the included script with the following command:

python -c "from macrobond_data_api.util import *; save_proxy_to_keyring()"

Using of system keyring for credentials

Note: If u are using a proxy see "Using of system keyring for http proxy" first.

When using WebClient it is recommended to use the system keyring to store the API credentials. This can be done easily by running the include script using this command:

python -c "from macrobond_data_api.util import *; save_credentials_to_keyring()"

Supported keyrings

Examples

You can find examples how to use the API here.

Getting support

Support options

Sub-modules

macrobond_data_api.com
macrobond_data_api.common

The core classes and types of the Macrobond Data API.

macrobond_data_api.util

Utility methods for Macrobond Data API.

macrobond_data_api.web

Functions

def delete_serie(series_name: str) ‑> None

Delete one series.

Parameters

series_name : str
The name of the series.

Returns

None

Search for time series and other entitites.

Parameters

text : str
Optional set of keywords separated by space.
must_have_values : Dict[str, object]
Optional dictionary of values that must be present in the entity metadata. The value can be a single value or an array of values. If there are several values for an attribute, it means that either of them must be present.
must_not_have_values : Dict[str, object]
Optional dictionary of values that must not be present in the entity metadata. The value can be a single value or an array of values.
must_have_attributes : Union[Sequence[str], str]
Optional set of attributes that must be present in the entity metadata. The value can be a single value or a sequence of values.
must_not_have_attributes : Union[Sequence[str], str]
Optional set of attributes that must no be present in the entity metadata. The value can be a single value or a sequence of values.
include_discontinued : bool
Set this value to True in order to include discontinued entities in the search.

Returns

SearchResult

def entity_search_multi_filter(*filters: SearchFilter, include_discontinued: bool = False, no_metadata: bool = False) ‑> SearchResult

Search for time series and other entitites. You can pass more than one search filter. In this case the filters have to use different entity types and searches will be nested so that the result of the previous filter will be used as a condition in the subsequent filter linked by the entity type.

Parameters

*filters : SearchFilter
One or more search filters.
include_discontinued : bool
Set this value to True in order to include discontinued entities in the search.
no_metadata : bool
Set this value to True in order only return the entity names and no metadata, which is faster.

Returns

SearchResult

def get_all_vintage_series(series_name: str) ‑> GetAllVintageSeriesResult

Get all vintages of a series.

Parameters

series_name : str
The name of the series.

Returns

GetAllVintageSeriesResult

def get_entities(entity_names: Sequence[str], raise_error: bool = None) ‑> Sequence[Entity]

Download one or more entities.

Important: It is much more efficient to download more than one entity at a time.

However, downloading too many at a time is less efficient and can exhaust memory. A good habit is to download entities in batches of around 200.

Parameters

entity_names : Sequence[str]
The names of the entities.
raise_error : bool
If True, accessing the resulting entities raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

Sequence[Entity] The result is in the same order as in the request.

def get_many_series(series: Sequence[Union[str, Tuple[str, Optional[datetime.datetime]]]], include_not_modified: bool = False) ‑> Generator[Series, None, None]

Parameters

series : Sequence[Union[str, Tuple[str, Optional[datetime]]]]
A sequence of series names or a sequence of name plus a timestamp for the last modification.
include_not_modified : bool
Set this value to True in order to include NotNodified series.

Returns

Generator[Optional[Series]]

def get_many_series_with_revisions(requests: Sequence[RevisionHistoryRequest], include_not_modified: bool = False) ‑> Generator[SeriesWithVintages, None, None]

Download all revisions for one or more series. Specify a callback to receive the response series by series. This method is primarily intended for syncronizing a local database with updates.

You are expected to retain the LastModifiedTimeStamp, LastRevisionTimeStamp and LastRevisionAdjustmentTimeStamp for each series and use them in the next request. The attributes LastRevisionTimeStamp and LastRevisionAdjustmentTimeStamp might not be present in all responses.

This function returns a generator that will return the result in a streaming fashion to conserve memory since the result can be very large.

Parameters

requests : Sequence[RevisionHistoryRequest]
A sequence of series requests.
include_not_modified : bool
Set this value to True in order to include NotNodified series.

Returns

Generator[SeriesWithVintages]

def get_nth_release(nth: int, series_names: Sequence[str], include_times_of_change: bool = False, raise_error: bool = None) ‑> Sequence[Series]

Get one or more series where each value is the nth change of the value.

Parameters

time : nth
The nth change of each value.
series_names : str
The names of the series.
include_times_of_change : bool
Include information of the time each values was last changed.
raise_error : bool
If True, accessing the resulting series raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

Sequence[Series] The result is in the same order as in the request.

def get_observation_history(series_name: str, *times: datetime.datetime) ‑> Sequence[SeriesObservationHistory]

Get the revision of an observation.

Parameters

series_name : str
The name of the series.
times : datetime
One or more timestamps.

Returns

Sequence[SeriesObservationHistory]

def get_one_entity(entity_name: str, raise_error: bool = None) ‑> Entity

Download one entity.

Important: It is much more efficient to download more than one entity at a time.

See Api.get_entities.

Parameters

entity_name : str
The name the entity.
raise_error : bool
If True, accessing the resulting entity raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

Entity

def get_one_nth_release(nth: int, series_name: str, include_times_of_change: bool = False, raise_error: bool = None) ‑> Series

Get a series where each value is the nth change of the value.

Parameters

time : nth
The nth change of each value.
series_name : str
The name of the series.
include_times_of_change : bool
Include information of the time each values was last changed.
raise_error : bool
If True, accessing the resulting series raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

Series

def get_one_series(series_name: str, raise_error: bool = None) ‑> Series

Download one series.

Important: It is much more efficient to download more than one series at a time.

See Api.get_series.

Parameters

series_name : str
The name of the series.
raise_error : bool
If True, accessing the resulting series raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

Series

def get_one_vintage_series(time: datetime.datetime, series_name: str, include_times_of_change: bool = False, raise_error: bool = None) ‑> VintageSeries

Get one vintage series.

Parameters

time : datetime
The time of the vintage to return.
series_name : str
The name of the series.
include_times_of_change : bool
Include information of the time each values was last changed.
raise_error : bool
If True, accessing the resulting series raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

VintageSeries

def get_revision_info(*series_names: str, raise_error: bool = None) ‑> Sequence[RevisionInfo]

Get information about if revision history is available for a series and a list of revision timestamps.

Parameters

*series_names : str
One or more series names.
raise_error : bool
If True, accessing the resulting series raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

Sequence[RevisionInfo] The result is in the sane order as in the request.

def get_series(series_names: Sequence[str], raise_error: bool = None) ‑> Sequence[Series]

Download one or more series.

Important: It is much more efficient to download more than one series at a time.

However, downloading too many at a time is less efficient and can exhaust memory. A good habit is to download series in batches of around 200.

Parameters

series_names : Sequence[str]
The names of the series.
raise_error : bool
If True, accessing the resulting series raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

Sequence[Series] The result is in the same order as in the request.

def get_unified_series(*series_entries: Union[SeriesEntry, str], frequency: SeriesFrequency = SeriesFrequency.HIGHEST, weekdays: SeriesWeekdays = SeriesWeekdays.MONDAY_TO_FRIDAY, calendar_merge_mode: CalendarMergeMode = CalendarMergeMode.AVAILABLE_IN_ANY, currency: str = '', start_point: StartOrEndPoint = None, end_point: StartOrEndPoint = None, raise_error: bool = None) ‑> UnifiedSeriesList

Get one or more series and convert them to a common frequency and calendar.

Parameters

*series_entries : Union[SeriesEntry, str]
One or more names of series or SeriesEntry objects.
frequency : SeriesFrequency
Specifies what frequency the series should be converted to. By default, it will be converted to the highest frequency of any series.
weekdays : SeriesWeekdays
The days of the week used for daily series. The default is Monday to Friday.
calendar_merge_mode : CalendarMergeMode
The start date mode determines how the start date is calculated. By default the mode is to start when there is data in any series.
currency : str
The currency to use for currency conversion or omitted for no conversion.
start_point : StartOrEndPoint
The start point. By default, this is determined by the startDateMode.
end_point : StartOrEndPoint
The end point. By default, this is determined by the endDateMode.
raise_error : bool
If True, accessing the resulting entities raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

UnifiedSeries The result is in the same order as in the request.

Examples

from datetime import datetime, timezone
from macrobond_data_api.com import ComClient
from macrobond_data_api.common.types import SeriesEntry

with ComClient() as api:  # or WebClient

    print(api.get_unified_series("usgdp", "gbgdp").to_pd_data_frame())

    vintage = datetime(2012, 11, 1, tzinfo=timezone.utc)
    print(
        api.get_unified_series(
            SeriesEntry("usgdp", vintage=vintage),
            SeriesEntry("gbgdp", vintage=vintage),
        ).to_pd_data_frame()
    )
def get_vintage_series(time: datetime.datetime, series_names: Sequence[str], include_times_of_change: bool = False, raise_error: bool = None) ‑> Sequence[VintageSeries]

Get one or more vintage series.

Parameters

time : datetime
The time of the vintage to return.
series_names : str
The names of the series.
include_times_of_change : bool
Include information of the time each values was last changed.
raise_error : bool
If True, accessing the resulting series raises a GetEntitiesError. If False you should inspect the is_error property of the result instead. If None, it will use the global value Api.raise_error

Returns

Sequence[VintageSeries] The result is in the same order as in the request.

def metadata_get_attribute_information(*names: str) ‑> Sequence[MetadataAttributeInformation]

Get information about metadata attributes.

Parameters

*names : str
One or more names of metadata attributes.

Returns

Sequence[MetadataAttributeInformation] The result is in the same order as the attribute names in the request.

Examples

with ComClient() as api: # or WebClient

    # as objects
    print(api.metadata_get_attribute_information("Region", "Unit"))

    # as dict
    print(api.metadata_get_attribute_information("Region")[0].to_dict())

    # as data_frame
    print(api.metadata_get_attribute_information("Region")[0].to_pd_data_frame())
def metadata_get_value_information(*name_val: Tuple[str, str]) ‑> Sequence[MetadataValueInformationItem]

Get information about metadata values.

Parameters

*name_val : Tuple[str, str]
The attribute name and a value.

Returns

Sequence[MetadataValueInformationItem] The result is in the same order as the attribute names in the request.

Examples

with ComClient() as api: # or WebClient

    # as objects
    print(api.metadata_get_value_information(("RateType", "mole"), ("RateType","cobe")))

    # as dict
    print(api.metadata_get_value_information(("RateType", "mole"))[0].to_dict())

    # as data_frame
    print(api.metadata_get_value_information(("RateType", "mole"))[0].to_pd_data_frame())
def metadata_list_values(name: str) ‑> MetadataValueInformation

List all metadata attribute values of an attribute that uses a value list.

Parameters

name : str
The name of the metadata attribute

Returns

MetadataValueInformation

Examples

with ComClient() as api: # or WebClient

    # as objects
    print(api.metadata_list_values("RateType"))

    # as dict
    print(api.metadata_list_values('RateType').to_dict())

    # as data_frame
    print(metadata_list_values("RateType").to_pd_data_frame())
def upload_series(name: str, description: str, region: str, category: str, frequency: SeriesFrequency, values: Sequence[Optional[float]], start_date_or_dates: Union[datetime.datetime, Sequence[datetime.datetime]], day_mask: SeriesWeekdays = SeriesWeekdays.MONDAY_TO_FRIDAY, metadata: Optional[Dict[str, Any]] = None, forecast_flags: Optional[Sequence[bool]] = None) ‑> None

Upload an in-house time series.

Parameters

name : str
The name of the series.
description : str
The description of the series.
region : str
The region of the series.
category : str
The category of the series.
frequency : SeriesFrequency
The frequency of the series.
values : Sequence[Optional[float]]
The values of the series.
start_date_or_dates : Union[datetime, Sequence[datetime]]
The start date of the series or dates of the series.
day_mask : SeriesWeekdays
The days of the week used for daily series. The default is Monday to Friday.
metadata : Optional[dict]
The metadata of the series.
forecast_flags : Optional[Sequence[bool]]
The forecast flags of the series.

Returns

None