Getting Started with the ScopeGreen API

Updated 17 Apr 2025

Welcome to ScopeGreen, the sustainability-focused API of Scope4! This guide walks you through retrieving environmental Life‑Cycle‑Assessment (LCA) metrics via our REST API.

1 What is ScopeGreen?

ScopeGreen gives developers, researchers and sustainability professionals programmatic access to high‑quality environmental‑impact data for thousands of materials and products.

Key capabilities

• Access core metrics – Carbon Footprint, EF 3.1 Score, Land Use, and more.

• Flexible search – Query by item name, refine by year, geography, or domain (e.g. Materials & Products, Transport).

• Compare options – Ask for up to three ranked matches.

• Performance mode – Lite mode is currently the only operational mode. Supplying mode=pro will be accepted but internally treated as lite; full pro accuracy will be released soon.

• Unit conversion – pass unit=; supports mass, volume, area, energy, distance, time & combinations. See the Unit Conversion docs.

• Language support – Flag non‑English item names for auto‑translation.

• (Experimental web search integration is disabled for now.)

2 Authentication

Every request needs an API key in the Authorization header.

curl --request GET \
  --url "https://scopegreen-main-1a948ab.d2.zuplo.dev/api/metrics" \
  --header "Authorization: Bearer YOUR_API_KEY"

How to obtain a key

1. Submit the Builder Form or the Enterprise Form to request access.

2. We will get back to you in less than 24 hours.

3. Your key will be safely provided via email.

Soon an Authentication page will be made available. There you will be able to see your key and even rotate it.

Need help? → tom@scope4.dev

3 Quick start – your first call

Let's retrieve the carbon footprint for a cotton T‑shirt.

curl --request GET \
  --url "https://scopegreen-main-1a948ab.d2.zuplo.dev/api/metrics/search?item_name=cotton" \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "matches": [
    {
      "rank": 1,
      "matched_name": "Cotton",
      "metric": {
        "name": "Carbon footprint",
        "value": 1.314,
        "unit": "kg CO2 eq / kg"
      },
      "year": 2025,
      "geography": "USA",
      "source": "IDEMAT 2025RevA",
      "source_link": "https://www.ecocostsvalue.com/data-tools-books/",
      "conversion_info": "Unit conversion not requested."
    }
  ],
  "explanation": "The best match is 'Cotton USA' as it directly refers to cotton without specifying any particular processing or blend. It provides the requested carbon footprint metric."
}

4 Core endpoint – /api/metrics/search

Method GET /api/metrics/search

If nothing suitable is found:

{ "message": "No good match was found, retry with a different item name" }

5 Concepts

Available metrics – Carbon footprint, EF 3.1 Score, Land Use
Domain filters – Materials & Products (default) · Processing · Transport · Energy · Direct emissions Unit conversion – pass unit=; supports mass, volume, area, energy, distance, time & combinations.
Rate limiting – bursts return 429 Too Many Requests; exponential back‑off recommended.

6 Code snippets

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://scopegreen-main-1a948ab.d2.zuplo.dev/api/metrics/search"
params = {
    "item_name": "cotton t-shirt",
    "metric": "Carbon footprint",
    "mode": "lite",  # pro maps to lite until pro is launched
    "unit": "g"       # convert functional unit to grams
}
resp = requests.get(url, headers={"Authorization": f"Bearer {api_key}"}, params=params)
print(resp.json())

JavaScript

async function searchLcaBench() {
  const apiKey = 'YOUR_API_KEY';
  const params = new URLSearchParams({
    item_name: 'cotton t-shirt',
    metric: 'Carbon footprint',
    mode: 'lite',           // pro currently behaves as lite
    unit: 'g'
  });
  const url = `https://scopegreen-main-1a948ab.d2.zuplo.dev/api/metrics/search?${params}`;
  const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
  const data = await res.json();
  console.log(data);
}

7 Best practices

• Be precise with item_name (e.g. "cold‑rolled low‑carbon steel sheet").
• Narrow with domain and year when possible.
• Request 2‑3 matches to view alternatives.
• Handle errors (400/422 from validation, 429 rate‑limit, 500 server) gracefully.

8 Support

Questions, ideas or issues → tom@scope4.dev