API Reference

Introduction

Welcome to the Xtract API documentation!
Our API is meticulously crafted to provide you with an efficient and streamlined way to access comprehensive summaries of Environmental, Social, and Governance (ESG) themes published by companies. With our robust API, you can effortlessly retrieve data on company profiles and gain insights into their ESG performance through concise summaries of their annual and sustainability reports.

In this all-inclusive documentation, you'll discover in-depth information on how to authenticate with the API, navigate the available endpoints, and practical examples that demonstrate the optimal utilization of our Xtract API. Embark on your journey to explore the ESG landscape with our cutting-edge solution at your fingertips.

Getting started
‍

To begin your journey, you will require an API key. To obtain one, please contact our dedicated team to learn more about API Plans. .

Once you have secured an API key, include it in the Authorization header of your requests to authenticate with the API.The Xtract API is designed to prioritize simplicity and ease of use. Our solution offers a straightforward approach to accessing invaluable company information and report summaries. Our database is constantly updated to ensure you have access to the most recent information available.

‍

Authentication

To use the Xtract API, you must include an API key in the Authorization header of each request. To obtain an API key, please contact us here.

‍

Responses

Get Companies

The Get Companies endpoint retrieves a comprehensive list of companies available in our database.
The information includes the company name, country, country code, International Securities Identification Number (ISIN), and symbol. This endpoint provides you with an extensive selection of companies, for which you can obtain ESG-related summaries.
The result is returned as a JSON array, allowing seamless integration into your application for further processing or display.

‍


curl curl -X GET 'https://your-api-url.com/api/get-companies' -H 'Authorization: your-api-key'


  const axios = require('axios');

  axios.get('https://your-api-url.com/api/get-companies', {
    headers: {
      'Authorization': 'your-api-key'
    }
  })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });


import requests

# set your API key
api_key = ‘your-api-key’

# set the URL of the API endpoint to fetch data from
url = "https://client-summary-api-ilnlvag45a-od.a.run.app/api/get-companies"

# set the headers with the API key to authenticate the request
headers = {
    "Authorization": api_key
}

# send the GET request to the API endpoint with the headers
response = requests.get(url, headers=headers)

# check if the response status code is 200 (OK)
if response.status_code == 200:
    # if the response is successful, extract the JSON data and store it in the 'companies' variable
    companies = response.json()
else:
    # if the response is not successful, print an error message with the status code
    print("Error occurred. Status code:", response.status_code)

[  

{    "company_name": "Company A",   
     "country": "United States",   
     "country_code": "US",   
     "isin": "US1234567890",    
     "symbol": "COMPA"  }, 

{   "company_name": "Company B",   
    "country": "United Kingdom",    
    "country_code": "GB",   
    "isin": "GB9876543210",    
    "symbol": "COMPB"  },  …

]

Get Themes

The Get Themes endpoint returns a curated list of ESG themes available in the API, along with a description of each theme.
Each theme represents a specific aspect of environmental, social, and governance considerations that companies are expected to address in their annual and sustainability reports.
The result is returned as a JSON array, which developers can use to filter and categorize ESG data obtained through other endpoints in the API.


curl -X GET 'https://your-api-url.com/api/get-themes' -H 'Authorization: your-api-key'


const axios = require('axios');

const apiKey = 'your-api-key';
const url = 'https://your-domain.com/api/get-themes';

axios.get(url, {
  headers: {
    'Authorization': apiKey
  }
}).then(response => {
  console.log(response.data);
}).catch(error => {
  console.error(error);
});


import requests

# set your API key
apiKey = 'your-api-key'

# set the URL of the API endpoint to fetch data from
url = "https://client-summary-api-ilnlvag45a-od.a.run.app/api/get-themes"

# set the headers with the API key to authenticate the request
headers = {
    "Authorization": apiKey
}

# send the GET request to the API endpoint with the headers
response = requests.get(url, headers=headers)

# check if the response status code is 200 (OK)
if response.status_code == 200:
    # if the response is successful, extract the JSON data and store it in the 'themes' variable
    themes = response.json()
else:
    # if the response is not successful, print an error message with the status code
    print("Error occurred. Status code:", response.status_code)

[

{'description': 'The preservation and enhancement of the variety of living organisms and natural habitats, maintaining ecological balance and supporting the well-being of current and future generations.', 

'theme': 'Biodiversity and ecosystems'}, …

]

GET Summary

The Get Summary endpoint is designed to retrieve ESG-related summaries for a specified company symbol and country code.
The results can be further refined by providing optional query parameters such as year, document type (Annual Report or Sustainability Report), and ESG theme.
The response is returned as a JSON object, making it convenient for developers to integrate the data into their applications.

Query Parameters:‍

‍‘symbol’ (required): The symbol of the company for which to retrieve the summary data. This can be found in the get-companies endpoint. Example: ‘AAPL’.

‍‘country_code’ (required): The country code of the company for which to retrieve the summary data. This can be found in the get-companies endpoint. Example: ‘US’.

‍‘year’ (optional): The year of the document for which to retrieve the summary data. If not specified, the API will return the summary for the most recent year available. Example: ‘2021’.

‍‘doc_type’ (optional): The type of document to filter the results by. Valid options are "AR" for Annual Report and "SR" for Sustainability Report. If not specified, the API will return the best document for the selected theme. Example: ‘AR’.

‍‘theme’ (optional): The ESG theme to filter the results by. This can be found in the get-themes endpoint. If not specified, the API will return data for all available themes. Example: ‘Gender equality’.

Note that the ‘symbol’ and ‘country_code’ parameters are required, while the others are optional.
You can use these query parameters to fine-tune the data returned by the API and retrieve only the information that you need.

‍


curl -H "Authorization:your-api-key" "https://client-summary-api-ilnlvag45a-od.a.run.app/api/get-summary?symbol=RNO&country_code=FR"


const https = require('https');

const apiKey = 'your-api-key';

const url = `https://client-summary-api-ilnlvag45a-od.a.run.app/api/get-summary?symbol=RNO&country_code=FR`;

const options = {
  headers: {
    'Authorization': apiKey
  }
};

https.get(url, options, (res) => {
  let data = '';
  
  res.on('data', (chunk) => {
    data += chunk;
  });
  
  res.on('end', () => {
    if (res.statusCode === 200) {
      const summary = JSON.parse(data);
      console.log(summary);
    } else {
      console.log(`Request failed with status code ${res.statusCode}`);
    }
  });
  
}).on('error', (err) => {
  console.error(err);
});


import requests

# set your API key
apiKey =  'your-api-key'

url = 'https://client-summary-api-ilnlvag45a-od.a.run.app/api/get-summary'

params = {
    'symbol': 'RNO',
    'country_code': 'FR'
}

headers = {
    'Authorization': apiKey
}

response = requests.get(url, params=params, headers=headers)

if response.status_code == 200:
    summary = response.json()
else:
    print(f'Request failed with status code {response.status_code}')

{
  "doc_type": "ANNUAL REPORT",
  "theme": "Pollution prevention and emissions",
  "symbol": "CMPA",
  "isin": "US0000000000",
  "year": "2022",
  "summary": "Company A has made significant progress in reducing its carbon footprint...",
  "country": "United States"
}