Skip to Content
CarbonFooterv2.0

Issues & recommendations

Issue instances, the catalog endpoint, and recommendation tiers.

Issues are the actionable layer on top of raw measurements. They carry severity, context data, and optional estimated savings — separate from the observation-only assets and delivery namespaces.

One shape, forever

Every issue instance has the same shape regardless of detail tier:

Issue instance
{
  "id": "image_format",
  "severity": "high",
  "data": { "count": 8 },
  "estimatedSaving": { "value": 735000, "unit": "bytes", "estimated": true }
}

estimatedSaving is null when not estimable. When present, it always includes estimated: true.

The data object is a flat bag of scalars used for messageTemplate interpolation in the catalog. Keys vary by issue id but are stable within an id.

Recommendation tiers

Controlled by the recommendations request parameter:

Tierissues[]issueCatalogUse case
"summary" (default)lean instancesnullDashboards and SDKs that cache the catalog
"full"lean instancescopy for present idsOne-shot callers (PDFs, quick reports)

issueSummary is always populated regardless of tier.

The "none" tier was dropped pre-launch. Unrecognised values fall back to "summary".

Issue catalog

Static copy lives behind a separate endpoint — fetch once and cache:

GET /api/v2/issues?lang=en
Catalog response
{
  "version": "2.0",
  "lang": "en",
  "issues": {
    "image_format": {
      "title": "Use modern image formats",
      "messageTemplate": "{count} images aren't served as WebP or AVIF.",
      "whyItMatters": "Modern formats cut image transfer by 25–50%.",
      "howToFix": "Convert images to WebP/AVIF and serve via <picture> or your CDN.",
      "docsUrl": "https://carbonfooter.nl/learn/image-formats",
      "category": "images",
      "defaultSeverity": "high"
    }
  }
}

Render messages client-side with messageTemplate and data:

render-message.js
function renderMessage(template, data) {
  return template.replace(/\{(\w+)\}/g, (_, key) => String(data[key] ?? ''));
}

Issue categories

Issues are grouped by domain:

CategoryExample ids
Hosting & carbongreen_hosting, high_grid_intensity
Page weightpage_weight, too_many_requests
Imagesimage_format, image_lazyload, image_gif
Codejs_minify, css_minify, js_weight
Fontsfont_format, font_display, font_weight
Mediavideo_autoplay, embed_weight, iframe_lazyload
Third-partythird_party_weight, third_party_requests
Deliverycompression, caching, slow_ttfb, redirects

Thresholds are retunable without a version bump. New issue ids may be added at any time.

Ordering

Issues are sorted by severity (high → low), then by estimatedSaving.value descending.

On this page