Skip to Content
CarbonFooterv2.0

Conventions

Measure types, null handling, verdicts, and rounding rules.

These conventions apply across the entire v2 response. Understanding them prevents common integration mistakes.

Measure — value + unit

Every dimensioned quantity is a Measure, never a bare number:

Measure
{ "value": 650000, "unit": "bytes" }
{ "value": 180, "unit": "ms" }
{ "value": 0.9, "unit": "bytes", "estimated": true }

Units

UnitMeaning
bytesTransfer size
msMilliseconds
sSeconds
pxPixels
percentPercentage
gCO2eGrams CO₂ equivalent
gCO2e/kWhGrid carbon intensity

Rules

  • Dimensioned → Measure. Dimensionless → bare integer. Counts like requests, redirects, and asset totals are plain integers.
  • Units never appear in field names. There is no estimatedSavingBytes — only estimatedSaving: Measure.
  • estimated: true means the value is modelled, not observed. Absent when measured.

Null, never omitted

Every documented field is always present:

SituationValue
Unavailable scalarnull
Unavailable list[]
Unavailable objectnull
Opt-in list not requestednull (distinct from [])

Clients should treat null as "not available" and never infer values from absence.

Tri-state verdicts

Checks that can fail to run use a Verdict, not a boolean:

"true" | "false" | "unknown"

Applies to delivery.compression.document, assets.scripts.minified, hosting.green, and similar fields.

HTML browser storage policy uses browserCache (allowed | blocked | unknown) instead.

Rounding

Unit familyRounding
bytes, ms, s, px, percent, gCO2e/kWhIntegers
gCO2e4 significant figures at every magnitude

Significant figures prevent a tiny page from showing 0.0000 gCO2e (which reads as carbon-free) while avoiding false precision on heavy pages.

Request parameters never change meaning

Parameters may control cost and verbosity (screenshot, recommendations, include). They may never change what a returned number means. Two responses for the same URL must always be comparable.

Consumer obligations

Clients must:

  • Ignore unknown fields and enum members
  • Treat null as unavailable
  • Read units from the unit field
  • Not parse opaque strings (scanId, screenshot filenames)

On this page