---
title: "Coverage — which countries we hold data for, and how much"
method: GET
path: "/v1/coverage"
tags: ["Discovery"]
---

# Coverage — which countries we hold data for, and how much

`GET /v1/coverage`

## Request

- Base URL: `https://api.greencalculus.com`
- URL: `https://api.greencalculus.com/v1/coverage`
- Auth: none required

Open (no key). Per country: how many of 13 inventory families we hold, the row count in each, and a band (complete / partial / minimal). Answer "do you cover my country?" before integrating. Derived from the live corpus at request time, so it cannot drift from the data. Measures PRESENCE, not sufficiency — a country showing fuel:7 has seven fuel rows, which may not answer a given question; the response repeats this in a caveat field. Returns counts only, never factor values.

## Query parameters

- `country` string
- `family` string
- `min_score` integer

## Response `200`

Coverage matrix + meta (families, bands, filters) + caveat

- Coverage: Country × family coverage, generated from the live corpus. Scores measure PRESENCE of a family, never sufficiency — a country can score 13/13 and still lack the row you need.
  - `meta` object
    - `gc_version` string
    - `gc_updated` string, date
    - `countries` integer
    - `returned` integer
    - `families` object: The thirteen family slugs mapped to their human labels.
    - `bands` object: Counts per band. complete = 10+ of 13 families present, partial = 4–9, minimal = 1–3.
    - `filters` object
  - `coverage` object: Keyed by ISO3.
  - `caveat` string
  - `docs` string, uri
  - `receipt` Receipt: Deterministic tamper-evidence. To verify: remove the `receipt` and `attribution` keys from the response, sort every object's keys recursively, serialise to JSON with slashes and Unicode unescaped, and SHA-256 the result — it equals `receipt.id` with the `gcr_` prefix stripped. The receipt's own `verify` field states the same recipe.
    - `id` string
    - `algorithm` string
    - `mb_version` string
    - `verify` string: Plain-language instructions for recomputing the digest.

## Other responses

- `400`: Unknown parameter or unknown family — named in the error

---

[API](https://skmtc.dev/greencalculus/apis/greencalculus-api.md) · [All operations](https://skmtc.dev/greencalculus/apis/greencalculus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greencalculus/apis/greencalculus-api/revisions/2f742325958c?raw)