API

Everything the scanner does, as raw JSON. Access requires an API key, and we issue them manually for now. Get in touch and tell us what you're building.

Scan a website

GET https://co2.observer/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,
    "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:

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