ESG data in Python
Last update  June 2020
Operating System  Any
Tool  Python

Introduction

In the first tutorial we authenticated to the server and requested our token, and then retrieved some data, which happened to be historical pricing summaries data (i.e. bar data).

This tutorial covers ESG, i.e. Environmental Social Governance data retrieval.

After a brief introduction to ESG data, we shall cover the available API calls, as well as their input parameters and expected outputs.

A Python sample esgViews.py is available under the downloads tab.

Table of contents

  • What is ESG data ?
    • How can I access ESG data ?
  • What data are you entitled to ?
  • Data coverage: instrument universe and history
  • API calls parameters
    • Start and end
  • Output data format
    • Messages, validation of returned data
  • Calling up the data universe
  • Implementation
  • Run

What is ESG data ?

The ESG acronym stands for Environmental Social Governance. This is data that highlights how companies are rated on environmental, social and governance criteria.

The data is of 2 natures:

  • Measures
  • Scores

There are more than 400 measures (the actual number can vary depending on the company), which as their name indicates are measures of specific criteria, self reported by the companies. The type of data can be a boolean, a number, or eventually a string, depending on the nature of the underlying data. Here are a few areas that are covered:

  • Water and energy consumption and efficiency
  • CO2 emissions
  • Human rights
  • Women employees
  • Staff training
  • Health and safety
  • Etc.

Using the measures, we calculate a set of scores, i.e. analytics whose result is a number that indicates how well a company scores on various criteria. Some of these are on specific topics, like the Innovation Score, others are summaries, like the Environment, Social and Governance Pillar Score, which are overall ratings of these 3 pillars, and the ESG Score which is an overall score for the company, based on those 3 pillars. Scores have values between 0 and 1, 0 being the worst and 1 the best.

All these values are delivered on a yearly basis, i.e. there is one record per calendar year.

Please note that the source data for measures is self reported by the companies. Depending on when it is published, values for the preceding year might not be available.

How can I access ESG data ?

We plan to have 2 ways of accessing ESG data from the Refinitiv Data Platform:

  • By instrument, using specific queries - This is what this tutorial is about.
  • In bulk files - This will be available in Q2 2020.

What data are you entitled to ?

There are several levels of access to the data, that relate to the data usage (display on public or private websites), as well as the number of data fields and the depth of history available.

Depending on your contract, you might only be able to access a subset of the API calls described in this tutorial.

In case of doubt about your access rights, please contact your Refinitiv account manager.

Data coverage: instrument universe and history

Data is currently available for more than 8000 companies, with history going all the way back to 2002 (when available). Companies are regularly added to the list, and delisted companies are not removed.

API calls parameters

There are several API call parameters, that are common to most of the ESG API calls. Please note that they are case sensitive:

Parameter Mandatory? API calls where it applies Purpose Example value Default
universe Mostly All except the universe call Instrument identifier. Example codes for Apple Incorporated: none
The following codes are supported: AAPL.O
RIC1 4295905573
PermID2  
Cusip 37833100
ISIN  
OrgID US0378331005
Sedol  
Valoren 19775
Wert  
  2046251
To use several, separate them with commas.  
  908440
  865985
start Optional Measures and scores calls Start year -2 -2 (standard calls)
   
(number of years before the most recent year) -20 (full calls)
end Optional Measures and scores calls End year 0 0
(most recent year)
format Optional All calls Remove messages3 from output noMessages Messages are delivered
(this is the only possible value if it is set)

1ESG also supports special RICs that do not deliver market depth data, it is therefore possible to use BNPP.PA or BNPP.PA1, TEF.MC or TEF.MC1, MSFT.NB or MSFT.O.

2See Open PermID for information on what the PermID is, and how you can use it. RIC is the Reuters Identification Code.

3Messages are numeric codes that validate output fields.

Start and end

By default, API calls for standard data will return 3 years of history, and calls for full data will return all years history.

The optional start and end parameters can be used to restrict that range to a subset of years.

Note: for a standard call, start cannot be lower than -2. For a full call, start cannot be lower than -20.

API call Start End Result
universe not applicable not applicable  
basic not applicable not applicable 2017
standard not set not set 2015-2017
standard -1 0 2016-2017
standard -1 -1 2016
standard -3 -1 Error (start value should be between -2 and 0)
full not set not set All available history
full -3 -1 2014-2016
full -15 -15 2002
full -21 0 Error (start value should be between -20 and 0)

Output data format

The output of the calls is in JSON format. All calls deliver data with a common structure, each one contains the following objects:

  • links - number of data records
  • variability - defines if the number of records in the result will always be the same, or if it might change
  • universe - universe of instruments with data fields (some might not be available): RIC, company name, PermID, currency
  • data - requested data records (1 or more), each containing a set of fields
  • messages - validation of the data records
  • headers - description of the returned data fields

Here is an example, from the API call for basic data:

    	
            
instrument, periodenddate, TR.CSRReportingScope, TR.ESGPeriodLastUpdateDate, TR.


CO2EmissionTotal, TR.WomenManagers, TR.AvgTrainingHours


---------------


TRI.N, 2018-12-31, 100, 2019-11-29T00:00:00, 102300, 40, 19.4

Messages, validation of returned data

Messages are numeric codes that validate received output fields.

There is one message record per returned data record, and one message value per output field in a data record, as can be seen in the example above.

The meaning of the returned message codes is explained in the accompanying description record:

Code Meaning
-1 ok (the value is ok)
-2 empty (there is no available value)

As we saw previously, these messages can be disabled using the format=noMessages API call parameter.

Implementation

The code to get Environmental Social Governance data is implemented in the file: esgViews.py. The program begins by getting an Access token from the token library that we built in the first tutorial.

    	
            
accessToken = rdpToken.getToken();

The sample code runs various API calls, based on passed argument, which can be:

    	
            
-1 Show Basic View - default call if no argument is specified


-2 Show Standard Measures


-3 Show Full Measures


-4 Show Standard Scores


-5 Show Full Scores

All the measures and scores API call invoke a different REST endpoint but carry same parameters. For e.g. the resource endpoint for standard measures would be: https://api.refinitiv.com/data/environmental-social-governance/<VERSION>//views/measures-standard?universe=TRI.N.

Additionally, we will optionally define the JSON object for start and end date parameters:

    	
            
requestData = {


    "start": "-20",


    "end": "0",


    "format": "noMessages"


};

And finally make the request:

    	
            
dResp = requests.get(RESOURCE_ENDPOINT, headers = {"Authorization": "Bearer " + accessToken}, params = requestData);

The Access token has been sent as a "Bearer" in the "Authorization" header. If this token is not included, our request will be rejected. The response message from platform is a JSON object and has following signature:

    	
            
{


 "links": {


  "count": 1


 },


 "variability": "variable",


 "universe": [{


   "Instrument": "TRI.N",


   "Company Common Name": "Thomson Reuters Corp",


   "Organization PermID": "4295861160",


   "Reporting Currency": "USD"


  }


 ],


 "data": [["TRI.N", "2017-12-31", 100, "2018-12-20T00:00:00", 270587, 39, 61.04]],


 "messages": {


  "codes": [[-1, -1, -1, -1, -1, -1, -1]],


  "descriptions": [{


    "code": -1,


    "description": "ok"


   }


  ]


 },


 "headers": [{


   "name": "instrument",


   "title": "Instrument",


   "type": "string",


   "description": "The requested Instrument as defined bythe user."


  }, ...

Next, if the server did not reject the request: if dResp.status_code != 200: we display the result in a readable format. Our trivial example, loops over received JSON message and extracts all the returned headers and data points:

    	
            
for i in vData["headers"]:


    line = line + i["name"] + ", "


 


for d in vData["data"]:


    line = ""


    for pt in d:


        line = line + str(pt) + ", "

Please refer to API documentation for more details on data API.

Run

Execute the sample from command line using command:

    	
            
python esgViews.py

You should see the following output: