EcoIQ Intelligence API

REST API — v1 · Base URL: https://ecoiq.uk/api/v1/

REST / JSON 218+ Companies 25+ Countries ML Scores SHAP Explainability 6-Pillar Scoring

Overview

The EcoIQ API provides programmatic access to ethical industrial intelligence scores, company profiles, country intelligence, ML model outputs, and harm signal matrices for 218+ global companies.

All responses are JSON. Dates are ISO 8601. Scores are 0–100 (higher = better). The API is designed for integration into ESG dashboards, investment screens, and regulatory reporting tools.

Authentication

All endpoints support unauthenticated access with reduced rate limits. Authenticated requests use an API key, which must be included in one of these headers:

X-API-Key: your-api-key-here
# or
Authorization: Bearer your-api-key-here

API keys are issued per subscriber tier. Request a key at ecoiq.uk/contact or via the pricing page.

Rate Limits

Tier	Requests / Day	Price	Best For
Unauthenticated	20 / day	Free	Exploration only
Explorer	100 / day	Free with registration	Researchers, journalists
Professional	2,000 / day	£599 / month	Fund analysts, ESG officers
Enterprise	50,000 / day	£2,500 / month	Asset managers, banks, DFIs

Error Codes

Code	Meaning
`400`	Bad request — missing or invalid parameter
`401`	Authentication required or invalid API key
`403`	Forbidden — insufficient tier for this endpoint
`404`	Company / country not found
`429`	Rate limit exceeded — wait until next day
`500`	Internal error — contact support

Companies

GET /api/v1/companies/ Paginated list

🌐 Public

Param	Type	Description
`q`	string	Search name / description
`sector`	string	Filter: energy, mining, manufacturing…
`country`	string	Filter by country name
`min_score`	float	Minimum EcoIQ score (0–100)
`max_score`	float	Maximum EcoIQ score (0–100)
`cluster`	string	ML cluster label (e.g. "ESG Leader")
`anomaly`	true/false	Show only ML-flagged anomalies
`page_size`	int	Results per page (max 200, default 50)

curl https://ecoiq.uk/api/v1/companies/?sector=energy&min_score=70 \
  -H "X-API-Key: your-key"

GET /api/v1/companies/{slug}/ Full company profile

🌐 Public

Returns the complete company profile including all pillar scores, harm signals, 12-month score history, and ML intelligence fields.

curl https://ecoiq.uk/api/v1/companies/orsted/ \
  -H "X-API-Key: your-key"

GET /api/v1/companies/{slug}/scores/ Scores only — lightweight

🌐 Public

Compact response with EcoIQ scores, pillar breakdown, and ML outputs only. Ideal for bulk portfolio integration.

GET /api/v1/companies/{slug}/harm-signals/ Harm signal matrix

🌐 Public

Returns the 5-vector hidden harm signal analysis: pollution severity, controversy risk, transparency deficit, profit extraction, and transition gap.

Leaderboard

GET /api/v1/leaderboard/ Top-N ranked companies

🌐 Public

Param	Type	Description
`top`	int	Number of companies (default 100, max 500)
`sector`	string	Filter by sector

curl "https://ecoiq.uk/api/v1/leaderboard/?top=10§or=energy" \
  -H "X-API-Key: your-key"

Countries

GET /api/v1/countries/ Country list with aggregate scores

🌐 Public

GET /api/v1/countries/{slug}/ Country intelligence detail

🌐 Public

Returns country AI intelligence summary, national EcoIQ index (average of domestic companies), and top-10 companies.

Search

GET /api/v1/search/ Cross-entity search

🌐 Public

Param	Type	Description
`q`	string (required)	Search term — matches name, slug, sector, country, description

curl "https://ecoiq.uk/api/v1/search/?q=saudi+aramco" \
  -H "X-API-Key: your-key"

ML Insights

GET /companies/{slug}/ml-insights.json Live ML inference

🌐 Public

Runs on-demand ML inference for a company: GBR score with SHAP feature attribution, anomaly detection, K-Means cluster assignment, and 12-month forecast.

curl https://ecoiq.uk/companies/orsted/ml-insights.json

{
  "company": "Ørsted",
  "scoring": {
    "score": 89.6,
    "confidence": 0.998,
    "top_features": [
      {"feature": "score_pollution_footprint", "impact": 14.641},
      {"feature": "score_reduction_progress",  "impact": 10.68}
    ]
  },
  "anomaly":    {"anomaly_score": -0.657, "is_anomaly": true},
  "cluster":    {"cluster": 2, "label": "ESG Leader"},
  "prediction": {"score_12m": 89.5, "delta": 0.0}
}

Field Reference

Field	Type	Description
`ecoiq_score`	decimal	Deterministic 6-pillar score (0–100)
`ml_score`	decimal	GBR-predicted score (0–100)
`ml_score_confidence`	float	Model confidence (0–1)
`ml_predicted_score_12m`	decimal	12-month OLS trend forecast
`ml_cluster_label`	string	K-Means peer group archetype
`is_anomaly`	boolean	Isolation Forest anomaly flag
`anomaly_score`	float	Isolation Forest score (negative = more anomalous)
`harm_penalty`	float	Points deducted for pollution / controversy / governance failures
`ecoiq_total_score`	float	6-pillar weighted total (CompanyProfile level)
`pollution_level`	string	none / low / medium / high / critical

Ready to integrate EcoIQ data?

Request an API key — Explorer tier is free.

Request API Key →