sustainalytics 0.3.5

This is a package that helps clients access the Sustainalytics API

Introduction

Starting with sustainalytics 0.2.0, the package is compatible with API v2 only. If a v1-compatible version is needed, please install version 0.1.2 via this command:

pip install sustainalytics==0.1.2

This python package provides access to Sustainalytics API (Application Programming Interface) service which provides developers with 24x7 programmatic access to Sustainalytics data. The API has been developed based on market standards with a primary focus on secure connectivity and ease of use. It allows users to retrieve and integrate Sustainalytics data into their own internal systems and custom or third-party applications

This document is meant to provide developers with python sample code for the Sustainalytics API service. Technical documentation can also be found on the dedicated website for the API.

Installation

Install the package via pip with code below:

pip install sustainalytics

To Upgrade:

pip install --upgrade sustainalytics

Connection

A clientid and a secret key must be provided by the Sustainalytics Team in order to access the API. See connection via python:

from sustainalytics.api import API

# Access
client_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
client_secret_key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

con = API(client_id=client_id, client_secretkey=client_secret_key)

# Returns Bearer
print(con.access_headers)

Helper functions

These helper functions are meant to help you in calling the endpoint functions.

fieldClusterIds = con.get_fieldClusterIds()
print(fieldClusterIds)

fieldIds = con.get_fieldIds()
print(fieldIds)

fieldsInfo = con.get_fieldsInfo()
print(fieldsInfo)

productIds = con.get_productIds()
print(productIds)

packageIds = con.get_packageIds()
print(packageIds)

packageInfo = con.get_packageInfo()
print(packageInfo)

Endpoints

DataService

The DataService enables the user to call the research data associated with the companies in the universe of access. Within this service there are 6 endpoints, as described below.

• DataService - Get research data by query
• DataService/{identifier} - Get research data by identifier
• DataServiceWTimestamps - Get timestamped research data by query
• DataServiceWTimestamps/{identifier} - Get timestamped research data by identifier
• LastChangesSince - Get last changes since research data by query
• LastChangesSince/{identifier} - Get last changes since research data by identifier

The code below shows you how to extract data from these endpoints:

Get Data

Retrieves data from the DataService or from the DataServiceWTimestamps endpoint. 'identifiers' and 'productId' are mandatory arguments.

identifiers : A list of security or entity identifiers separated by comma. You can obtain a list of EntityIds from the con.get_universe_entityIds(keep_duplicates=True)

productid : The Product ID. Only one integer value is accepted. You can obtain a list of ProductIds from the con.get_productIds()

timestamps : Optional boolean argument present only in the get_data function that lets you choose between timestamped research data and research data.

In addition to the 3 arguments, one of the following arguments can also be chosen:

packageIds : A list of package ids separated by comma. You can obtain a list of PackageIds from the con.get_packageIds()

fieldClusterIds : A list of field cluster ids separated by comma. You can obtain a list of FieldClusterIds from the con.get_fieldClusterIds()

fieldIds : A list of field ids separated by comma. You can obtain a list of FieldIds from the con.get_fieldIds()

AddCoverageCompanies : Optional boolean argument (default False). When set to True, the API will return data for the coverage company (IssuerId) instead of returning the research entity (ResearchEntityId).

# GetData for research data (default dtype='json') - DataService endpoint.
research_data = con.get_data(identifiers=[], productId=x, packageIds=[], fieldClusterIds=[], fieldIds=[], dtype='dataframe', timestamps=False, AddCoverageCompanies=False)
print(research_data)

# GetData for timestamped research data (default dtype='json') - DataServiceWTimestamps endpoint.
timestamped_research_data = con.get_data(identifiers=[], packageIds=[], productId=x, fieldClusterIds=[], fieldIds=[], dtype='dataframe', timestamps=True, AddCoverageCompanies=False)
print(timestamped_research_data)

# GetData for time series research data (default dtype='json') - TimeSeriesData endpoint.
timestamped_research_data = con.get_data(identifiers=[], packageIds=[], productId=x, fieldClusterIds=[], fieldIds=[], dtype='dataframe', time_series=True, AddCoverageCompanies=False)
print(timestamped_research_data)

# GetData for timestamped research data (default dtype='json') - TimeSeriesDataWTimestamps endpoint.
timestamped_research_data = con.get_data(identifiers=[], packageIds=[], productId=x, fieldClusterIds=[], fieldIds=[], dtype='dataframe', time_series=True, timestamps=True, AddCoverageCompanies=False)
print(timestamped_research_data)

# GetData including coverage companies (IssuerId-based data when applicable)
coverage_data = con.get_data(identifiers=[], packageIds=[], productId=x, fieldClusterIds=[], fieldIds=[], dtype='dataframe', time_series=True, timestamps=True, AddCoverageCompanies=True)
print(coverage_data)

Get LastChangesSince

Retrieves data from the LastChangesSince endpoint. 'startdate' and 'productId' are mandatory arguments.

Additional arguments compared to get_data:

startdate : Date filter for last changes query. The format of the date is "yyyy-mm-dd". Can retrieve data only for last 3 months from current date.

# Get LastChangesSince returns timestamped research data that has changed since a specific date (default dtype='json') - LastChangeSince endpoint
last_changes_since_data = con.get_LastChangesSince(startdate="x", productId=x, identifiers=[], packageIds=[], fieldClusterIds=[], fieldIds=[], dtype='dataframe', AddCoverageCompanies=False)
print(last_changes_since_data)

# Get LastChangesSince including coverage companies (IssuerId-based data when applicable)
last_changes_since_coverage = con.get_LastChangesSince(startdate="x", productId=x, identifiers=[], packageIds=[], fieldClusterIds=[], fieldIds=[], dtype="dataframe", AddCoverageCompanies=True)
print(last_changes_since_coverage)

Product Structure & Definitions

Each product is built from data packages and each data package is built from field clusters. The datafields are the smallest components of the product structure.

The Product Structure service provides an overview of the data fields available in the Sustainalytics API and the unique FieldIds linked to each of these data fields. Within this service there are three endpoints, as described below.

• FieldDefinitions - Get field definitions
• FieldMappings - Get product structure
• FieldMappingDefinitions - Get product structure with field definitions

The code below shows you how to extract data from these endpoints:

# FieldDefinitions (default dtype='json')
field_definitions = con.get_fieldDefinitions(dtype='dataframe')
print(field_definitions)

# FieldDefinitions for time series data (default dtype='json')
field_definitions = con.get_fieldDefinitions(time_series=True, dtype='dataframe')
print(field_definitions)

# FieldMappings (default dtype='json')
field_mappings = con.get_fieldMappings(dtype='dataframe') 
print(field_mappings)

# FieldMappings for time series data (default dtype='json')
field_mappings = con.get_fieldMappings(time_series=True, dtype='dataframe') 
print(field_mappings)

# FieldMappingDefinitions (default dtype='json')
field_mapping_definition = con.get_fieldMappingDefinitions(dtype='dataframe')
print(field_mapping_definition)

# FieldMappingDefinitions for time series data (default dtype='json')
field_mapping_definition = con.get_fieldMappingDefinitions(time_series=True, dtype='dataframe')
print(field_mapping_definition)

# Extra FieldDefinition (non-Swagger) (default dtype='json')
full_field_definitions = con.get_fullFieldDefinitions(dtype='dataframe')
print(full_field_definitions)

Reports

The ReportService endpoint allows users to retrieve a list of all available PDF report types by ReportId, ReportType, and ReportName for companies belonging to the universe of access. (Please note this Endpoint is not part of the standard API product.)

• ReportService - Get available report types
• ReportService/{identifier} - Get available report types by entity identifier
• ReportService/url/{identifier}/{reportId} - Get report url (recommended endpoint as it has the fastest response time)

The code below shows you how to extract data from these endpoints:

# ReportService - returns all the available report fieldIDs (reportids) (default dtype='json')
report_info = con.get_pdfReportInfo(productId=x, dtype='dataframe') 
# Where x can be any integer value of existing product ids (for example, 10 for Corporate Data)
print(report_info)

# ReportService(identifier/reportid) - returns the URL to given pdf report for specified companies (if available) (default dtype='json')
report_identifier_reportid = con.get_pdfReportUrl(identifier=x, reportId=y)
print(report_identifier_reportid)

The function supports only 1 identifier and reportID per call.

Universe of Access

The UniverseOfAccess endpoint allows users to determine the list of EntityIds contained in the universe of access (all permissioned securities lists).

• UniverseOfAccess - Get universe of access

# UniverseofAccess - returns all universe constituents (default dtype='json')
universe = con.get_universe_access(dtype='dataframe')
print(universe)