PREFACE
This covers the Boosted API version 2.x. Python 3 is required. The python library can be downloaded from:
https://insights.boosted.ai/downloads
API usage examples are provided below.
APP API FUNCTIONS & DETAILS
See our regularly updated reference guide for complete API functionality.
AUTHENTICATION
Boosted.ai will have issued you a secret API key to authenticate yourself with. This key should be treated like a password: keep it encrypted at rest and only send it over HTTPS.
NOTES
The model_id can be found in the UI by clicking on the copy to clipboard button next to the model name on a model’s summary page.
The dataset_id can be found by navigating to https://insights.boosted.ai/custom-data and clicking copy to clipboard next to the dataset that you’d like to update.
The portfolio_id can be found in the UI by clicking on the copy to clipboard button next ‘Portfolio Settings’ that appears after clicking the gear next to the portfolio name.
USAGE & EXAMPLES
Allocations
To get the allocations for a portfolio on all dates:
from boosted.api import api
df = api.getAllocationsForAllDates(‘api_key’, ‘portfolio_id’)
This will pull portfolio allocations for all dates. To get allocations for a specific date, pass in the date:
from boosted.api import api
import datetime
df = api.getAllocationsForDate(‘api_key’, ‘portfolio_id’, date=datetime.date(2021,10,4), rollback_to_last_available_date=(True))
The result is a dataframe with columns isin, symbol, country, currency, price, allocation, company_name, shares_traded, shares_owned, allocation_delta, and has_trade_signal. To download the dataframe as a .csv file:
from boosted.api import api
import datetime
import pandas as pd
df = api.getAllocationsForDate(‘api_key’, ‘portfolio_id’, date=datetime.date(2021,10,4), rollback_to_last_available_date=(True))
print(df)
columns = df['allocations']
df = pd.DataFrame.from_dict(columns, 'columns', None, None)
df.to_csv('allocations.csv', index=False)
Dense Signals
Download a csv file containing dense signals for a given portfolio and model:
from boosted.api import api
get_signals = api.getDenseSignals(‘api_key’, ‘model_id’, ‘portfolio_id’, 'signals file name.csv')
The resulting csv will be downloaded to the current directory.
Rankings
All of the examples below pull the most recent rankings data using datetime.date.today(). If you want the rankings on a specific date, pass in the date using datetime.date(2021, 10, 4).
To get ranking 2.0 explain data for a given date:
from boosted.api import api
import datetime
df = api.getRankingExplain(‘api_key’, ‘model_id’, datetime.date.today())
The resulting dataframe will be indexed on ISINs and Feature Names, and contain columns data_value, explain_weight, and sorted_explain. To get the ranking 2.0 analysis data for a given date:
from boosted.api import api
import datetime
df = api.getRankingExplain(‘api_key’, ‘model_id’, datetime.date.today())
The resulting dataframe will be indexed on data buckets and feature names, and contain columns num_times, positive_pct, std_dev, and average. To get the most recent rankings data for a portfolio:
from boosted.api import api
import datetime
df = api.getRankingsForDate('api_key', 'portfolio_id', datetime.date.today(), True, None, False)
Rankings are defined by a dataframe with columns symbol, ISIN, country, currency, rank, companyName, and delta.
Model Universes
To get the universe for a model:
from boosted.api import api
df = api.getUniverse(‘api_key’, ‘model_ID’, None)
The date is optional. If you want the universe on a specific date, pass in the date. If you leave out a date, the returned table will include start and end dates for inclusion of a stock. If a date is passed in, only a list of stocks will be returned. To modify a universe (only future dates are allowed):
from boosted.api import api
df = api.updateUniverse(‘api_key’, ‘model_ID’, ‘new_universe’, date )
Universes are defined by a dataframe with columns ISIN, Country, Currency. Please set ISIN as the index.
Datasets
Types
There are three types of datasets: dependent data, global data, and independent data. All datasets must have an ISO formatted date (YYYY-MM-DD) as the index column.
- Dependent datasets are specific to stocks. Stocks are identified by ISINs. The first columns must be date, ISIN, 3-character ISO country code, and 3-character currency code.
- Dependent data uploads must use ISINs.
- Global datasets are data that can be used in stock models or custom strategy models. They are not specific to a single stock or security. Examples include interest rates and other macroeconomic data. The column column must be a date.
- Independent datasets are specific to custom strategies. The first columns must be date and strategy name.
Creation
Datasets may be created in the UI and updated via this API. This API may also be used to create new datasets. Once a dataset has been created, variables from the dataset may be included in Boosted models during model creation.
This API works best with Pandas DataFrames. They are used to store the datasets and to also represent stock universes.
To add a new dependent dataset:
from boosted.api import api
import pandas as pd
df = pd.read_csv(‘filename’, index_col=[0], parse_dates=True)
new_dataset = api.addDependentDataset(‘api_key’, df, 'name for dataset')
The filename is the name of the .csv file containing the data you’d like to upload. For information on formatting the upload file please visit knowledge-base.boosted.ai/knowledge/integrated-data. To add data to an existing dependent dataset
from boosted.api import api
import pandas as pd
df = pd.read_csv(‘filename’, index_col=[0], parse_dates=True)
new_dataset = api.addDependentData(‘api_key’, ‘dataset_id’, df)
To export the dataset:
from boosted.api import api
df = api.exportDependentDataset( your_API_key, dataset_ID )
The new data must have the same columns as the original dataset. As before, the data is passed in as a Pandas DataFrame.
To query the status of a dataset:
from boosted.api import api
api.queryDataset( your_API_key, dataset_ID )
ADVANCED USAGE
The API calls mentioned above are convenient wrappers to get started quickly. If you want finer grained control of the API, you may use these calls instead.
import boosted.api as api
from datetime import datetime
client = api.BoostedClient( your_API_key )
Creating a new dataset
Creating a new dataset requires defining a schema for the dataset. The most convenient method is to induce a schema from a Pandas DataFrame.
new_schema = api.inferDataSetSchema("My new dataset name", dataframe)
Then, create a new dataset with the schema which returns a dataset ID.
dataset_ID = client.createDataset(new_schema.toDict())
Then, upload the new dataset.
result = client.add_dependent_dataset(dataset_ID, dataframe)
You can query the dataset to verify that it is ready. When it is ready (status is AVAILABLE), you can use this dataset when creating new models.
result = client.query_dataset(dataset_ID)
Sample output is:
{ 'created': '2020-07-22T17:09:58.44158Z',
'fileSize': None,
'id': '053d3b4b-2cc4-4a7a-xxxx-xxxxxxxxxxxx',
'name': 'test data',
'ownerId': '076beab4-984d-43d5-xxxx-xxxxxxxxxxxx',
'region': None,
'status': 'AVAILABLE',
'type': 'STOCK',
'universeId': 'f1d57356-5a4c-4979-xxxx-xxxxxxxxx',
'validFrom': [2015, 1, 8],
'validTo': [2015, 11, 19]}
Adding data to an existing dataset
Dependent Data
client.add_dependent_data( dataset_ID, a_Pandas_DataFrame )
Independent Data
client.add_independent_data( dataset_ID, a_Pandas_DataFrame )
The column names must match the ones used in the original dataset.
Exporting data
This call will return your data as a Pandas DataFrame. Pass in datetime objects for the dates. A maximum of one year can be retrieved per call. The default is to return one year of data ending today.
Dependent Data
df = client.export_dependent_data( dataset_ID, start = start_date, end = end_date )
Independent Data
df = client.export_independent_data( dataset_ID, start = start_date, end = end_date )
Inference
To retrieve inference signals:
results = client.get_inference( model_ID, inference_date )
If there are no inference results available or if there is an existing inference job running for the model ID and date, no results will be returned. If you want get_inference() to block until the results are ready,
results = client.get_inference( model_ID, inference_date, block = True )
This will poll every ten seconds to see if your inference results are ready. You can always retrieve historical inference results if they exist.