Getting Started with the ScopeGreen API

Updated 5 May 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](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.
4. Soon an Authentication page will be made available. There you will be able to see your key and even rotate it.

Need help? → tommaso@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](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/](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

Parameter	Type	Required	Notes
item_name	string	✓	Max 100 chars
metric	string		Default Carbon footprint
year	string		≥ 2020. Default empty
geography	string		Max 50 chars. Default empty
num_matches	int (1‑3)		Default 1
unit	string		Functional‑unit conversion. Default empty; see the Unit Conversion docs
mode	string		lite (current) · pro (alias for lite ⚠️)
domain	string		Filter domain category. Default: Materials & Products
not_english	bool		true → auto‑translate item_name. Default false
web_mode	bool		Disabled – will be false for now

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](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
}
headers = {"Authorization": f"Bearer {api_key}"}

resp = requests.get(url, headers=headers, params=params)
print(resp.json())

JavaScript

async function searchScopeGreen() {
  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}`;

  try {
    const res = await fetch(url, {
       method: 'GET',
       headers: { Authorization: `Bearer ${apiKey}` }
    });
    const data = await res.json();
    console.log(data);
  } catch (error) {
    console.error("Error fetching data:", error);
  }
}

searchScopeGreen();

---

7 Interactive Tutorial (Google Colab)

Want to try the API live without writing code from scratch? We've prepared an interactive Google Colab notebook that guides you through making requests and exploring parameters.

Click here to open the Interactive Tutorial in Google Colab

You'll need your API key to run the examples.

---

8  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.

---

9  Support

Questions, ideas or issues → tommaso@scope4.dev