Developers

API reference

Everything the scanner does, as raw JSON: emissions, grades, transfer breakdowns, green hosting and improvement recommendations.

Authentication#

All API requests require a key, passed as the key query parameter.

We issue keys manually for now, free of charge. Get in touch and tell us what you're building.

Scan a website#

Scans a domain (or returns the cached result) and responds with the full carbon report.

GET/api/v1/scan?url=example.com&key=YOUR_KEY

Parameter	Description
`url`	The website to scan. We normalize to the domain and test the homepage.
`key`	Your API key.
`fresh`	Optional. Set to `1` to force a new scan instead of a cached result (cache: 7 days). Fresh scans take 30-60 seconds.

Response#

{
  "ok": true,
  "cached": true,
  "model": "Sustainable Web Design v4",
  "site": {
    "domain": "example.com",
    "url": "https://co2.observer/site/example.com",
    "finalUrl": "https://example.com/",
    "rating": "A+",
    "co2": {
      "gramsFirstView": 0.0104,
      "gramsPerVisit": 0.0078
    },
    "transfer": {
      "bytes": 70400,
      "formatted": "70.4 kB",
      "breakdown": {
        "document": { "bytes": 1256, "requests": 1 },
        "image": { "bytes": 69144, "requests": 2 }
      }
    },
    "energyKwh": 0.000021,
    "greenHost": true,
    "greenHostedBy": "Example Green Host",
    "greenCheckOk": true,
    "performanceScore": 1,
    "cleanerThan": 97,
    "recommendations": {
      "potential": {
        "rating": "A+",
        "gramsFirstView": 0.0071,
        "savedGrams": 0.0033,
        "savedBytes": 22400,
        "next": null
      },
      "items": [
        {
          "id": "modern-image-formats",
          "title": "Serve images in modern formats",
          "savedBytes": 22400,
          "savedGrams": 0.0033
        }
      ]
    },
    "scanned": 1757246400
  }
}

Errors#

Errors come back with an appropriate HTTP status and {"ok": false, "error": "..."}:

Status	Meaning
`401`	Missing or invalid API key
`422`	Invalid or missing `url`
`429`	Daily request limit reached (resets at midnight UTC)
`502`	The scan itself failed (site unreachable, measurement service busy, …)

Fair use#

Keys have a daily request limit. Cached responses are cheap; fresh scans (fresh=1) are expensive for us, so please only force them when you need up-to-date numbers.

Badge#

The badge needs no key. It's a plain SVG image reflecting the latest scan of a domain:

GET/badge/example.com.svg

<a href="https://co2.observer/site/example.com">
  <img src="https://co2.observer/badge/example.com.svg" width="200" height="44"
       alt="CO2 emissions rating for example.com">
</a>

Add ?theme=dark for the dark variant.