--- title: "Resolve one factor by canonical key (value + full provenance)" method: GET path: "/v1/factors/{key}" tags: ["Factors"] --- # Resolve one factor by canonical key (value + full provenance) `GET /v1/factors/{key}` ## Request - Base URL: `https://api.greencalculus.com` - URL: `https://api.greencalculus.com/v1/factors/{key}` - Auth: HTTP bearer ## Path parameters - `key` string, required ## Query parameters - `as_of` string ## Response `200` Factor with value, source id, source reference, data version - FactorLookup: One factor with its value and the full audit envelope. Served from the edge KV store. - `meta` object - `value` number, nullable: Convenience top-level copy of factor.factor.value. - `unit` string, nullable - `gas` string, nullable - `factor` FactorRow: One corpus row as returned by browse/search. Carries the full row INCLUDING factor.value — the browse endpoint is open and unmetered by design, because our data is overwhelmingly open-licensed at source and gating it would make this API worse than the original publisher. What a paid plan adds is the right to REDISTRIBUTE, not the ability to read. (Note: the MCP search_factors tool DOES project rows down to key/name/section — that projection is deliberate and specific to that tool.) - `key` string - `name` string, nullable - `section` string, nullable - `activity_type` string, nullable - `factor` object - `value` number, nullable - `unit` string, nullable - `gas` string, nullable - `basis` string, nullable - `gwp_set` string, nullable - `gwp_set_basis` string, nullable: How we know the GWP set — "published" where the source states it, "inferred" where we deduced it. null means not recorded, which is deliberately NOT the same as published. - `country_iso3` string, nullable - `uncertainty` Uncertainty, nullable: The publisher's own stated range, never derived by us. null means NOT RECORDED — explicitly not a claim that no uncertainty exists. - `low` number, nullable - `high` number, nullable - `basis` string, nullable - `published_as` string, nullable: The publisher's exact wording, e.g. "±30-50%". - `uncertainty_basis` string, nullable: "none_published" means the publisher states plainly that no range exists. null means not recorded — a different fact from silence. - `source` SourceRef: Provenance to the line. Carried on 100% of rows — where in the source document the value was read, not just which document. A workbook cell where the publisher ships a workbook (DEFRA); otherwise the table, annex clause or page they did ship (IPCC, CBAM, ECCC). - `id` string - `cell_ref` string - `retrieved` string, date - `scope` object, nullable - `ghg_protocol` string, nullable - `category` string, nullable - `components` object, nullable: Per-gas decomposition keyed by gas (co2, ch4, n2o…), each with its own cell_ref. Lets a consumer re-base AR5↔AR6 without us. - `note` string, nullable: Includes what the publisher did NOT provide, stated verbatim. - `citation` FactorCitation: The canonical citation for one factor row, built by the API (src/citation.ts) and printed VERBATIM by every official client (Sheets add-in, JS and Python SDKs, MCP). Format: ". — , cell , retrieved . via GreenCalculus data version , factor . ". On GET /v1/factors/{key} the version is the one actually SERVED, so a ?as_of= lookup cites the pin. Present on rows from 2026-09-09. The format is a published specification, free for anyone to implement against their own data: https://greencalculus.com/developers/citation/ - `text` string - `source_id` string, nullable - `cell_ref` string, nullable - `version` string, nullable - `proof_url` string, nullable - `licence` object: The licence this row is published under, and whether the Business redistribution grant covers it. Present on the open browse from MB v2026.181 — the full terms, the required credit and the publisher are listed once per source under meta.licences. Absent (not empty) where no licence is on record: an empty value would read as "no licence applies". - `name` string - `redistributable` boolean - `provenance` Provenance: Where the number came from and whether you may republish it. Built from the source registry — src/envelope.ts. - `source_id` string, nullable - `source_name` string, nullable - `publisher` string, nullable: The organisation, in one spelling (MB `publisher`). - `issuer` string: The issuing descriptor of this edition (MB `body`), present only when it differs from publisher. - `url` string, nullable - `cell_ref` string, nullable - `retrieved` string, date, nullable - `licence` string, nullable - `redistributable` boolean, nullable: Whether the Business redistribution grant covers this row. Fails closed — a source whose licence has not been assessed is false, not null. - `redistributable_basis` string, nullable - `update_cadence` string, nullable - `overrides_source` object: Present only when this row carries a licence its source does not (a publisher republishing third-party data under its own terms, e.g. CBAM Annex II). licence, redistributable and redistributable_basis above are then the ROW's; this block keeps the source's own answer beside them. - `source_redistributable` boolean, nullable - `since` string, nullable: Data version at which the row-level answer was recorded. - `attribution_required` string, nullable - `source_ref` string, nullable: Where the restricting text was read. - `verification` Verification: What was actually checked — computed at serve time, not asserted. - `components_sum_to_value` boolean, nullable: Whether the per-gas components sum to the headline. null where the row carries no components — the absence of a check is not a failed check. - `gwp_set` string, nullable - `gwp_set_basis` string, nullable - `uncertainty` Uncertainty, nullable: The publisher's own stated range, never derived by us. null means NOT RECORDED — explicitly not a claim that no uncertainty exists. - `low` number, nullable - `high` number, nullable - `basis` string, nullable - `published_as` string, nullable: The publisher's exact wording, e.g. "±30-50%". - `uncertainty_basis` string, nullable - `source_note` string, nullable - `served_from` string - `served_version` string - `version_pin` object: Present only when ?as_of= was sent — and not even then if the key did not exist at an archived version you asked for, which falls back to the browse envelope instead. `matched: false` means the requested version is not in the archive and the CURRENT value was served — check it before treating a response as pinned. - `attribution` Attribution, nullable: The credit the licence requires, or null on a plan that waives it. Was a bare STRING before 2026-08-25; the original string is preserved unchanged at `text`. `html` is a ready-to-paste anchor so that complying is less work than not complying, and `url` points at the public proof page for the exact factor and data version this answer used — your own audit evidence, not a marketing link. - `text` string: The plain credit line. Identical to the string this field used to be. - `html` string: A single anchor, no classes and no styling, ready to paste. - `url` string, nullable: Proof page for the factor this answer used, pinned to the data version — e.g. https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.181. Null where no single factor identifies the answer. The version is deliberate: an unversioned link would silently re-point at whatever the figure becomes. - `required` boolean: Whether this plan must display the credit. Reports the licence position, not a technical control. - `proof_urls` string[]: Every factor used by this answer, as a public proof URL pinned to the data version. A portfolio calculation may list many; cite per line from here. Contains no request data — each URL is a fact about the GreenCalculus corpus and is identical for every caller. ## Other responses - `401`: Missing/invalid key - `404`: Unknown key, or a key with no row at the requested ?as_of= version --- [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)