Python SDK & API¶

The Quantamatics platform includes a Python SDK for developing data functions and applications that work with alternative datasets and company fundamental data. The following will provide both an in-depth summary of every feature present in the Python SDK & API as well as an overview of how to use these features to start working with data.

Error Codes¶

Quantamatics provides standard HTTP response codes to show success or failure of a request. General status codes: 2XX indicates success, 4XX indicates error due to request, 5XX indicates error due to the Quantamatics server.

Authentication¶

Quantamatics uses JWT Tokens to authenticate users. These Tokens may be cached depending on settings within the Session Class. To manipulate data using the Quantamatics API, you’ll need to set your Token by authenticating your user with your respective credentials. This can be done using the Session class and its login() method.

from quantamatics.core.APIClient import Session
session = Session()
session.login(user = "SomeEmail@example.com", password = "password")

Note that the user and password values should be the exact same as the username and password values used when registering for your Quantamatics account. If ever an exception is raised stating the token has not been set, simply use the login() method to authenticate.

Using Quantamatics API Gateway¶

Quantamatics enables the publication of functions to be consumed via REST API and the Quantamatics API Gateway module of the SDK offers access to these APIs in a standard interface including function listing and metadata details.

Getting All Functions of the API¶

Every Quantamatics API function available to you can be listed through the use of the API Gateway module.

To begin, import the necessary modules including pandas, Session, and the API Gateway.

from quantamatics.core.APIClient import Session
from quantamatics.core.APIGateway import APIGatewayClient
import pandas as pd

Then, simply create a new session and authenticate with your credentials.

session = Session()
session.login(user = 'YOUR EMAIL', password = 'YOUR PASSWORD') #create session and login

Finally, create an API_Gateway object and call the getAPIList() method.

apiClient = APIGatewayClient() # create Gateway object
methodsDF = apiClient.getAPIList() #returns all Quantamatics methods

The above will create a variable methodsDF which will be a DataFrame containing all the functions available as part of the Quantamatics API.

Getting Function Metadata¶

To understand the purposes, features, and parameters of any given API function, you can use the API Gateway module and its methods. First, import the necessary modules and initialize the session then use the following methods.

apiClient = APIGatewayClient() # create Gateway object
methodsDF = apiClient.getAPIMetaData('Get FQ Forecast')

The above returns the metadata for the specific API function ‘Get FQ Forecast’.

Since this metadata is in the format of a list with a single dictionary inside, you can work with the metadata as you would with any array and dictionary.

methodsParams = methodsDF[0]["params"]

The above returns the parameters for the function ‘Get FQ Forecast’

Working with the Security Master¶

The Security Master module contains the properties and concepts for any given Company such as its Instrument or Symbology. Through these classes KPIs, Calendar Periods, Financial Statements and other concepts from the Fundamentals module may be accessed.

Making a Universe¶

To create a Universe, i.e. a set of Instruments, start by simply importing the appropriate classes from the Security Master module namely the Universe class.

from quantamatics.core import settings
from quantamatics.core.APIClient import Session
from quantamatics.data.securityMaster import Universe

Now, simply use the Universe Constructor and pass in the parameters you wish to use to narrow the scope of Instruments.

For instance, to see all instruments within the Consumer Discretionary Sector and Specialty Retail industry while using Bloomberg’s symbology, the appropriate call would be the following.

uni = Universe(sector = 'Consumer Discretionary', industry = 'Specialty Retail', instrumentSymbologyType='Bloomberg')

Universe Data Frames¶

The resulting value within uni will be a Universe Object, however the main point of interest is its DataFrame property. Use the following call to print out the DataFrame held within the object, uni. Given these parameters there should be several companies listed within the DataFrame.

print(uni.UniverseDF)

This DataFrame outlines a few things: the instrument names juxtaposed with the instrument IDs, the symbols juxtaposed with the exchanges and symbology types, and finally the sector names juxtaposed with the industry names. Here’s another example Universe creation.

software = Universe(sector = "Information Technology", industry = "Software",  instrumentSymbologyType='Bloomberg')

Here, all the available Software stocks have been put into a single Universe object called software. Here’s the contents of the held DataFrame.

	instrument_id	instrument_name	symbol
0	161	Intuit Inc. - INTU-NASDAQ	INTU US EQUITY
1	567	Zynga Inc. - ZNGA-NASDAQ	ZNGA US EQUITY
2	42	NortonLifeLock Inc. - NLOK-NASDAQ	NLOK US EQUITY
3	181	Activision Blizzard, Inc. - ATVI-NASDAQ	ATVI US EQUITY
4	154	Microsoft Corporation - MSFT-NASDAQ	MSFT US EQUITY
5	384	Adobe Inc. - ADBE-NASDAQ	ADBE US EQUITY

	Exchange	symbology_type	sector_name	industry_name
0	NASDAQ	Bloomberg	Information Technology	Software
1	NASDAQ	Bloomberg	Information Technology	Software
2	NASDAQ	Bloomberg	Information Technology	Software
3	NASDAQ	Bloomberg	Information Technology	Software
4	NASDAQ	Bloomberg	Information Technology	Software
5	NASDAQ	Bloomberg	Information Technology	Software

As you can see, all the companies should have the same symbology type, sector name and industry name. Information such as instrument_id can also be found here and used to instantiate other classes.

If instead, the goal was to create a Universe with a specific instrument, a specific company, such as Bed Bath and Beyond, simply provide their instrumentSymbol.

uni = Universe(instrumentSymbol = 'BBBY US EQUITY', instrumentSymbologyType='Bloomberg')

The resulting DataFrame will show the aforementioned properties for only the given instrument.

Creating a Company¶

The Company object can be used to quickly find information about a given company after instantiating its object. Information such as its sector and industry can be found this way.

To create a company, first import the class from the Security Master module, then either instantiate it through its instrumentID or companyID.

from quantamatics.core import settings
from quantamatics.core.APIClient import Session
from quantamatics.data.securityMaster import Company

#instantiating through instrumentID
company1 = Company(instrumentID = 280)

#instantiating the same company through companyID
company2 = Company(companyID = 168)

Once a company has been made, several properties of that company become accessible. The following are all the potential properties of a company object that may be printed.

company1.companyID
company1.companyName
company1.sectorName
company1.industryName
company1.industryGroupName
company1.verticalName
company1.subverticalName

Creating an Instrument¶

Instruments represent the stock of a company, and it will be the main access point for all fundamental financial data. Creating an instrument object can be done in two ways. Either the instrument’s symbol or the instrument’s id need to be provided.

Instrument Ids may readily be found through a Universe or company object. In addition, the instrumentSymbologyType needs to be provided so that the Quantamatics API knows which type of symbol is being provided.

The following are several examples of ways in which an instrument may be created.

#Creating an instrument with knowledge of instrument symbol

from quantamatics.core import settings
from quantamatics.core.APIClient import Session
from quantamatics.data.securityMaster import Instrument

bbby = Instrument(instrumentSymbol= "BBBY US EQUITY", instrumentSymbologyType = "Bloomberg")

#Creating an instrument through a Universe

from quantamatics.core import settings
from quantamatics.core.APIClient import Session
from quantamatics.data.securityMaster import Instrument, Universe

uni = Universe(sector = 'Consumer Discretionary', industry = 'Specialty Retail', instrumentSymbologyType='Bloomberg')

firstSymbol = uni.UniverseDF["symbol"].iat[0] #grabbing symbol of the first listed instrument
firstID = uni.UniverseDF["instrument_id"].iat[0] #grabbing id of the first listed instrument

firstInstrument = Instrument(instrumentSymbol = firstSymbol)

#OR

firstInstrument = Instrument(instrumentID = firstID)

Preloading¶

While initializing a new Instrument object, there’s an option to provide a preLoadLevel. Depending upon the preLoadLevel, certain fundamental data may automatically be preloaded. For instance, if the financial statements of a particular instrument are sure to be needed, these statements may be instantiated alongside the Instrument itself.

The following are examples of setting a preLoadLevel.

from quantamatics.core import settings
from quantamatics.core.APIClient import Session
from quantamatics.data.securityMaster import Instrument

# No preloading, all data will be loaded as needed
bbby = Instrument( preLoadLevel =  0, instrumentSymbol= "BBBY US EQUITY", instrumentSymbologyType = "Bloomberg")

# Preload level of 1, a Company object will be preloaded within the Instrument object
bbby = Instrument( preLoadLevel =  1, instrumentSymbol= "BBBY US EQUITY", instrumentSymbologyType = "Bloomberg")

# Preload level of 2, a CalendarPeriods and Company object will be preloaded within the Instrument object
bbby = Instrument( preLoadLevel =  2, instrumentSymbol= "BBBY US EQUITY", instrumentSymbologyType = "Bloomberg")

# Preload level of 3, a FinancialStatement, CalendarPeriods, and Company object will be preloaded within the Instrument object
bbby = Instrument( preLoadLevel =  3, instrumentSymbol= "BBBY US EQUITY", instrumentSymbologyType = "Bloomberg")

Getting Instrument Data¶

An Instrument object will contain several getter methods to obtain information about the instrument. To access this information, first be sure to properly instantiate the instrument along with any necessary preloading.

from quantamatics.core import settings
from quantamatics.core.APIClient import Session
from quantamatics.data.securityMaster import Instrument

bbby = Instrument( preLoadLevel =  3, instrumentSymbol= "BBBY US EQUITY", instrumentSymbologyType = "Bloomberg")

From here, any data from the company can be found through the use of the following getter methods.

bbbyCompany = bbby.getCompany()
bbyCalendarPeriods = bbby.getCalendarPeriods()
bbbyFinancialStatement = bbby.getFinancialStatement()
bbbyBrands = bbby.getBrands()
bbbySymbology = bbby.getSymbology()

With this data, KPIs and other fundamental data may be analyzed for any given instrument. Paired with Universes, instruments all within the same sector may quickly be compared.

Working with Fundamental Data¶

Working with Fundamental Data refers to Calendar Periods, Key Performance Indicators, and balance sheets as they relate to any given Instrument.

Accessing an Instrument’s Financial Statement¶

To access an Instrument’s FinancialStatement object, either use a pre-load level of 3 when making an Instrument, or manually create a FinancialStatement object using the intended instrument’s instrumentID as shown below

#pre-loaded instrument method
bbby = Instrument( preLoadLevel =  3, instrumentSymbol= "BBBY US EQUITY", instrumentSymbologyType = "Bloomberg")
statement = bbby.getFinancialStatement()

#manual calling of FinancialStatement Constructor
from quantamatics.data.fundamentals import FinancialStatement, KPI
statement = FinancialStatement(instrumentID = 280)

From here, you’ll want to see the actual contents of the FinancialStatement object, which is essentially a collection of Key Performance Indicators. Therefore, simply use the getKPIList() method within a FinancialStatement object as shown below.

from quantamatics.data.fundamentals import FinancialStatement, KPI
statement = FinancialStatement(instrumentID = 280)

kpiList = statement.getKPIList().head()

print(kpiList)

Accessing Key Performance Indicator data¶

A FinancialStatement object can further be used to retrieve KPI objects which have their own data. Below is an example on how to access a KPI from a FinancialStatement object.

from quantamatics.data.fundamentals import FinancialStatement, KPI
statement = FinancialStatement(instrumentID = 280)

kpi = statement.getKPIs(primary_only = True)[0]

From here, simply invoke the respective methods to access data within the KPI.

#KPI Name
print(curKPI.kpiName)

#KPI Reported History
print(curKPI.getKPIHistory().head())

#KPI Consensus Mean Last Estimate History
print(curKPI.getLatestEstimate().head())

#KPI Consensus Mean Point in Time History
print(curKPI.getEstimateHistory().head())

Accessing Quarterly Calendar Period Data of an Instrument¶

Much like with Financial Statements, Calendar Periods can be accessed through the preloading of an instrument or by manual input of an instrumentID.

curInstrument = Instrument(instrumentSymbol = curInstrumentSymbol, preLoadLevel = 2)
periods = curInstrument.getCalendarPeriods()

#or

calendar = CalendarPeriods(instrumentID = 280)
periods = calendar.getCalendarPeriods()

print(periods.head())

This will print the details of the CalendarPeriods’ data frame. Note that these details may differ in terms of time period depending on the value provided for the useReportedForCurrentQuarter parameter.

Working with Panels¶

Panels allow for the interaction with 3rd Party Data. In the Quantamatics API, Panels follow the factory design pattern. Much of what can be done with Instruments may also be done to Panels.

Getting a Panel using the Panel Factory¶

To get a Panel, simply use the PanelFactory method getPanel() and provide the specific panelName for the panel. The following uses the getPanel() method with the example Facteus panel.

from quantamatics.providers.panelFactory import panelFactory

panel = panelFactory.getPanel(panelName = "USCP Summary v3.5 - Backtest")

Loading Data¶

The load data function is one of the most important for using Panels. Most methods such as aggregateDataToCalendarPeriods() required data to be loaded on the Panel. While this function is entirely dependent on the class, the following is how data is loaded using the Facteus example.

#necessary imports
from quantamatics.providers.panelFactory import PanelFactory
from quantamatics.data.securityMaster import  Instrument
from quantamatics.core.APIClient import Session

#create panelFactory
panelFactory = PanelFactory()
session = Session()

#get appropriate panel and instrument
curPanel = panelFactory.getPanel('USCP Summary v3.5 - Backtest')
curInstrument = Instrument(instrumentSymbol = 'DKS US EQUITY', preLoadLevel = 2)

#load data using instrument
curPanel.loadData(instrumentObj = curInstrument, dimensions = ['Date', 'Region'])

Aggregating Data¶

After getting a Panel using the PanelFactory, several methods become available. Additionally, the panelName may be used within several previously mentioned classes such as the Universe class. A common method for Panels is aggregating data with aggregateDataToCalendarPeriods(). To start, begin with the following imports.

from quantamatics.providers import panelFactory
from quantamatics.providers import Facteus, TenTenData
from quantamatics.data.securityMaster import  Instrument
from quantamatics.core.APIClient import Session
from quantamatics.core import settings

From here, simply create a PanelFactory and Session object.

settings.DefaultSymbologyType = settings.SymbologyTypes.Facteus
session = Session()
PanelFactory = panelFactory.PanelFactory()

At this point, the panel, instrument, and calendar periods object can be made.

curPanel = PanelFactory.getPanel('USCP Summary v3.5 - Backtest')
curInstrument = Instrument(instrumentSymbol = 'DKS US EQUITY', preLoadLevel = 2)
curCalendarPeriods = CalendarPeriods(instrumentID = curInstrument.instrumentID, useReportedForCurrentQuarter = True)

Before aggregating Data, the DataFrame associated with the panel must be populated. This can be done with the loadData() function.

curPanel.loadData(instrumentObj = curInstrument, dimensions = ['Date', 'Region'])

Now, the aggregateDataToCalendarPeriods() method can be called, using the calendar periods of the “DKS US EQUITY” instrument. The method will return an aggregated DataFrame that can be stored in the curPanelDF variable.

curPanelDF = curPanel.aggregateDataToCalendarPeriods(calendarPeriodsObj = curCalendarPeriods, completeCurrentQuarter = False, dimensions = ['Region'])