Introduction

In the first tutorial we authenticated to the server and requested our token, and then retrieved some 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.

We shall illustrate this with requests in Postman. These calls are included in the Postman collection, 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
• Basic data for public websites
• Standard data for private websites
• Full data for the professional package

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 Corporate 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:

¹ESG 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.

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

³Messages are numeric codes that validate output fields.

As all API calls use the GET method, the API parameters are set in the URL of the call to the API. Their order is not important. Example:

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.

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 (the headers section was truncated in this exerpt):

Note: if a returned value is null, that means no data is available. If it is 0, then it means a value exists, and it is zero.

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:

Output:

After the count of results, variability and universe objects, we get the actual data for the universe of instruments.

Fields are the PermID, the primary RIC and the company common name, you can use these to map between a name, a RIC and a PermID:

This is followed by the messages with their descriptions (except if messages were disabled):

At the end, we find the headers, i.e. the definitions of the 3 data fields:

ESG supports special RICs that do not deliver market depth data (like BNPP.PA1, TEF.MC1, MSFT.NB), but this call will only deliver the main RICs (BNPP.PA, TEF.MC, MSFT.O).

Basic data for public websites

This API call delivers the latest value for a limited set of data, including mainly the following measures: CO2 emissions in tonnes, percentage of women managers and average hours of training per employee.

Parameters: universe (mandatory), format (optional)

Examples:

Output:

The (nearly) complete output can be seen here.

After the count of results and the variability, we get the universe record which describes the instrument, followed by the data, the messages and the headers.

Here is the actual data, for Allianz:

We can understand the data by using the returned header fields. They show that we received the values for ALVG.DE for the end of the latest current available year (2018). The reporting scope (100) means 100% of the companies activities are covered by the ESG report. We know when the ESG auditor last updated the metrics (2019-09-20), the total CO2 emissions (285866 tonnes), the percentage of women managers (37.8%) and the average hours of training per year per employee (24).

Standard data for private websites

API calls for standard data will return 3 years of history, except if the start and end parameters were used to restrict that range to a subset of years.

There are 2 API calls for standard data, one for measures that delivers more than 400 data fields (the actual number can vary depending on the company), and one just for scores that delivers 16 scores. The measures call actually also includes the scores.

Parameters: universe (mandatory), format (optional), start and end (optional)

Examples:

Output:

After the count of results and the variability, we get the universe record which describes the instrument, followed by the data, the messages and the headers.

Here is an exerpt of the measures-standard data for Allianz (which starts with the 16 scores, which are also delivered by the scores-standard call):

We can understand the data by using the returned header fields. They show that we received the values for ALVG.DE for the end of the latest current available year (2018). The overall combined ESG score was 48.07 (this score on the 3 pillars is overlayed with the controversies score), the ESG score was 89.89 (without taking controversies into account), the controversies score is 6.25. And so on ...

Here is an exerpt of the scores data for Allianz, containing all the latest scores :

It contains the same data as the first part of the measures call illustrated above.

Full data for the professional package

API calls for full data will return all years of history, except if the start and end parameters were used to restrict that range to a subset of years.

There are 2 API calls for full data, one for measures that delivers more than 400 data fields (the actual number can vary depending on the company), and one just for scores that delivers 16 scores. The measures call actually also includes the scores.

Parameters: universe (mandatory), format (optional), start and end (optional)

Examples:

Output:

The output is similar to that of the standard calls, but with more records as it can deliver the full history.