Alerts API: Articles

ESG & SDG Historical Alerts Data Dictionary

The TextReveal® Alerts API exposes an endpoint named v2/articles/esg and v2/articles/sdg that gives the possibility to retrieve documents for an entity of a universe.


GET /v2/articles/esg and /v2/articles/sdg

Endpoint Details

Endpoint: /v2/articles/esg and /v2/articles/sdg

Method: GET

Description: Access historical alerts data related to Environmental, Social, and Governance aspects for one or multiple entities.

Parameters

entity

  • Description: Entity name, ISIN, Ticker or website to use for extraction of historical data.
  • Example: apple
  • Warning: Cannot be used at the same time as universe_id parameter. If both are mentioned, the request will be rejected.

universe_id

  • Description: Universe Permanent ID to use for extraction of historical data. This ID can be retrieved with Universe Route.
  • Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
  • Warning: Cannot be used at the same time as entity parameter. If both are mentioned, the request will be rejected.

from

  • Description: Start date of Article extraction.
  • Expected format: YYYY-MM-DDThh:mm:ssZ
  • Mandatory field: Yes

to

  • Description: End date of Article extraction.
  • Expected format: YYYY-MM-DDThh:mm:ssZ
  • Mandatory field: Yes

field

  • Description: Select a field to return. If not provided, all fields are returned.
  • Supported fields: category, nb_articles, link, date, dashboard_url, language, negative, positive, intensity, source, sub_categories, taxonomy_keywords, title
  • Defaults: all

filter

  • Description: Select a filter to apply during article search. All filters provided are used with an 'AND' condition.
  • Supported fields: category, nb_articles, link, date, dashboard_url, language, negative, positive, intensity, source, sub_categories, taxonomy_keywords, title

size

  • Description: Number of rows to retrieve.
  • Defaults: 10

search_after

  • Description: document_id from which to execute search request (can be last of previous page to perform paging)

format

  • Description: Choose the response format (json or csv)
  • Default: json

Output Response Example

{
  "count": 0,
  "data": [
    {
      "category": "string",
      "dashboard_link": "string",
      "date": "2023-11-20T15:09:58.335Z",
      "document_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "entity_name": "string",
      "entity_website": "string",
      "intensity": 0,
      "isin": [
        "string"
      ],
      "language": "string",
      "link": "string",
      "nb_articles": 0,
      "negative": 0,
      "positive": 0,
      "source": "string",
      "sub_categories": [
        "string"
      ],
      "summary": "string",
      "taxonomy_keywords": [
        "string"
      ],
      "ticker": [
        "string"
      ],
      "title": "string"
    }
  ],
  "page": 0,
  "page_count": 0,
  "total": 0
}

Output fields description

Field Description
count Number of documents returned by the request
data List of documents returned by the request
page_count Number of pages needed to get all the documents
total Total number of documents
Field of each document Description
category

ESG: E: “Environment”, S: “Social”, G: “Governance”

SDG: SDG:1, SDG:2, …SDG:17
dashboard_link SESAMm Dashboard link to access the article
date Date of the document
document_id Unique identifier of the document
entity_name SESAMm name of the entity
entity_website Website of the entity
intensity The magnitude of the article, ranges from 1 to 5
isin List of ISIN of the entity
language Language of the article
link External link to access the article
nb_articles Number of articles identified with the same title
negative Probability that the article is negative
positive Probability that the article is positive
source Website link
sub_categories Sub-categories of the controversy
summary Summary of the controversy (main article only)
taxonomy_keywords Keywords matching the taxonomy in the document
ticker List of ticker of the entity
title Title of the article

💡 INTENSITY SCORE

The intensity score uses negative sentiment, article dispersion and empirical ESG risk measures to determine how likely an article is to represent a high-risk ESG controversy. Scores follow a power law distribution, with many 0-2 scores representing low-risk but relevant items and a much smaller number of higher risk items scored 3-5.