Specification · version 1
One line that says what a number is, who published it, which cell of their workbook it came from, which version you used, and where anyone can check it. Returned on every factor this API serves — and free for anyone to adopt, including people who do not buy anything from us.
Every factor returned by the API carries a citation object. Its text field is the canonical form, meant to be printed verbatim:
UK grid electricity — location-based (generation). UK Government GHG Conversion Factors 2026 — Department for Energy Security and Net Zero (DESNZ), cell 'UK electricity'!E25, retrieved 2026-06-18. via GreenCalculus data version 2026.189, factor grid.gbr.electricity.location_based. https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.189
Print it as given. Do not reformat, re-order or abbreviate it — the order carries meaning, and the trailing URL is what makes the rest checkable.
| Field | What it is | Example |
|---|---|---|
text | The canonical citation string. Print verbatim. | see above |
source_id | Our stable identifier for the publisher record. | DEFRA_2026 |
cell_ref | The exact cell in the publisher’s own workbook the value was transcribed from. | 'UK electricity'!E25 |
version | The data version the value was served at. | 2026.189 |
proof_url | A public, keyless verification page, pinned to that version. | verify.greencalculus.com/<key>@<version> |
The string names DESNZ before it names us, and says via GreenCalculus rather than by GreenCalculus. That is deliberate and it is not modesty.
We did not measure the UK grid. DESNZ did. A citation that put our name where theirs belongs would be wrong on the facts, and it would also be useless: a format that promotes the intermediary above the source is one that no auditor will accept and no competitor will ever adopt. Secondary credit is the only position that makes a format adoptable, and an adopted format is worth far more to us than a flattering one.
If you republish our data under a Business or Enterprise licence, the per-row source and licence stay inside the data for the same reason — the numbers remain traceable to the people who produced them wherever they end up.
| Where | How |
|---|---|
| REST API | The citation object on every factor in GET /v1/factors and GET /v1/factors/{key}. No key needed to browse. |
| MCP | Returned by lookup_factor and lookup_factors alongside the value. |
| Google Sheets | =GC_CITE("grid.gbr.electricity.location_based") in the cell beside your factor. |
| By hand | Open any verification page and copy the citation it prints — the same string the API returns, assembled by the same builder, on a page that needs no account. |
A citation is only useful if it still resolves years after it was written, so version 1 carries commitments rather than intentions:
If we ever need to break one of these, it becomes version 2 and version 1 keeps working. A spec that quietly changes underneath the documents that used it is not a spec.
This format is free for anyone to adopt, including our competitors. There is no trademark on it, no attribution owed to us for using the shape, and no permission to ask for. Implement it against your own data if you want to; the structure is the useful part and we would rather it spread than stay ours.
What the licence does cover is the data: quoting a GreenCalculus value still follows the open-layer terms, and the credit line in the string is part of how that works on the Free and Developer tiers.
Link to https://greencalculus.com/developers/citation/. It is a stable URL and will not move. If you implement the format and want it listed here as an adopter, say so.
