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:
{ "value": 650000, "unit": "bytes" }
{ "value": 180, "unit": "ms" }
{ "value": 0.9, "unit": "bytes", "estimated": true }Units
| Unit | Meaning |
|---|---|
bytes | Transfer size |
ms | Milliseconds |
s | Seconds |
px | Pixels |
percent | Percentage |
gCO2e | Grams CO₂ equivalent |
gCO2e/kWh | Grid carbon intensity |
Rules
- Dimensioned →
Measure. Dimensionless → bare integer. Counts likerequests,redirects, and asset totals are plain integers. - Units never appear in field names. There is no
estimatedSavingBytes— onlyestimatedSaving: Measure. estimated: truemeans the value is modelled, not observed. Absent when measured.
Null, never omitted
Every documented field is always present:
| Situation | Value |
|---|---|
| Unavailable scalar | null |
| Unavailable list | [] |
| Unavailable object | null |
| Opt-in list not requested | null (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 family | Rounding |
|---|---|
bytes, ms, s, px, percent, gCO2e/kWh | Integers |
gCO2e | 4 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
nullas unavailable - Read units from the
unitfield - Not parse opaque strings (
scanId, screenshot filenames)