InvestVerte API Documentation

Authentication

The API uses Token Authentication. Include your token in the Authorization header on every request.

Authorization: Token <your_token>

To obtain a token, contact the administrator or use the login endpoint if available.

1. Companies

List of Companies

Retrieves a list of all available companies.

• URL: /api/companies/
• Method: GET

[
  {
    "symbol": "AAPL",
    "name": "Apple Inc."
  },
  ...
]

Company ESG Rating

Retrieves ESG rating details for a specific company. Choose between AI-generated data (ai) or historical data (legacy).

• URL: /api/esg/<symbol>
• Method: GET
• Query parameters (optional):
  • model (string): ai (default) or legacy
  • year (int): year of the data
  • frequency (string): report frequency (e.g. "Annual", "Quarterly")

[
  {
    "e": 85.5,
    "s": 78.2,
    "g": 90.1,
    "esg": 84.6,
    "year": 2023,
    "frequency": "Annual"
  }
]

2. Countries

List of Countries

• URL: /api/countries/
• Method: GET

[
  {
    "country_code": "FR",
    "country_descr": "France"
  },
  ...
]

Country Data

Retrieves average ESG statistics for a specific country.

• URL: /api/country/<symbol>
• Method: GET
• Query parameters (optional):
  • model (string): ai (default) or legacy
  • year (int): year of the data
  • frequency (string): report frequency

[
  {
    "symbol": "FR",
    "name": "France",
    "mean": 75.4,
    "median": 76.2,
    "year": 2023,
    "frequency": "Annual"
  }
]

3. Sectors

List of Sectors

• URL: /api/sectors/
• Method: GET

[
  {"sector": "Technology"},
  {"sector": "Finance"},
  ...
]

Sector Data

• URL: /api/sector/<symbol>
• Method: GET
• Query parameters (optional):
  • model (string): ai (default) or legacy

4. ETFs

ETF ratings are the holdings-weighted aggregation of the underlying companies' E/S/G/ESG scores, with independent re-weighting per pillar (holdings with a missing weight or score are excluded and the remaining weights are re-normalized to 100%). ETFs whose ESG coverage is below the reliability threshold are excluded from the results.

List of ETFs

• URL: /api/etfs/
• Method: GET
• Query parameters (optional):
  • model (string): legacy (default) or ai
  • month (string, YYYY-MM): holdings snapshot month. If omitted, the current/latest data is used.

[
  {
    "symbol": "IWDA.AS",
    "name": "iShares Core MSCI World UCITS ETF",
    "exchange": "AS",
    "score_e": 68.4,
    "score_s": 61.2,
    "score_g": 72.9,
    "score_esg": 67.5,
    "coverage_esg": 92.1,
    "nb_holdings_total": 500,
    "band_esg": "good"
  },
  ...
]

ETF ESG Rating

Retrieves the weighted ESG rating for a specific ETF.

• URL: /api/etf/<symbol>
• Method: GET
• Query parameters (optional):
  • model (string): legacy (default) or ai
  • month (string, YYYY-MM): holdings snapshot month. If omitted, the current/latest data is used.

{
  "symbol": "IWDA.AS",
  "name": "iShares Core MSCI World UCITS ETF",
  "exchange": "AS",
  "score_e": 68.4,
  "score_s": 61.2,
  "score_g": 72.9,
  "score_esg": 67.5,
  "coverage_e": 92.1,
  "coverage_s": 92.1,
  "coverage_g": 92.1,
  "coverage_esg": 92.1,
  "nb_valid_esg": 480,
  "nb_missing_esg": 20,
  "nb_holdings_total": 500,
  "band_esg": "good"
}

Status Codes

• 200 OK: Request successful.
• 400 Bad Request: Invalid parameters (e.g. incorrect year).
• 401 Unauthorized: Missing or invalid authentication token.
• 403 Forbidden: User is not validated or does not have necessary permissions.
• 404 Not Found: Resource (symbol, country, sector) does not exist.

Example Request (cURL)

curl -X GET "https://api.investverte.com/api/esg/AAPL?year=2023" \
     -H "Authorization: Token 1234567890abcdef"