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

keystring required

Query parameters

as_ofstring
Example:2026.175

Serve this factor as it stood at an ARCHIVED data version. On a hit you get the archived row, served_version is the version you asked for, and version_pin reports matched: true, reproducible: true. Two misses, and they behave differently. (1) The version is NOT in the archive: 200 carrying the CURRENT row, with version_pin.matched: false naming as_of_requested and listing every archived version available — unlike POST /v1/calculate/*?as_of=, which 400s instead. So read version_pin before treating a response as pinned; do not infer it from the status code. (2) The version IS archived but holds no row for this key — it did not exist yet, or was withdrawn at or before it: 404 not_found, naming the key and the version, and saying whether the key is in the CURRENT corpus so a real absence is distinguishable from a mistyped key. GET /v1/factors/{key}/history lists every version that recorded it. Case (2) returned 200 with the current value in a browse envelope until 2026-09-10; it now refuses, because serving a current value under a past version label is the one answer this endpoint must never give.

Response

Factor with value, source id, source reference, data version

metaobject
valuenumber nullable

Convenience top-level copy of factor.factor.value.

unitstring nullable
gasstring nullable
served_fromstring
served_versionstring
version_pinobject

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.

proof_urlsstring[]

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.

Example response

{
  "factor": {
    "key": "grid.gbr.electricity.location_based",
    "section": "grid",
    "activity_type": "purchased_energy",
    "factor": {
      "unit": "kg CO2e per kWh",
      "gas": "CO2e",
      "gwp_set": "AR5_100",
      "country_iso3": "gbr",
      "uncertainty": {
        "basis": "published"
      }
    },
    "source": {
      "id": "DEFRA_2026",
      "cell_ref": "'UK electricity'!E25",
      "retrieved": "2026-06-18"
    },
    "scope": {
      "ghg_protocol": "scope2"
    },
    "citation": {
      "text": "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.186, factor grid.gbr.electricity.location_based. https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.186",
      "source_id": "DEFRA_2026",
      "cell_ref": "'UK electricity'!E25",
      "version": "2026.186",
      "proof_url": "https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.186"
    },
    "licence": {
      "name": "Open Government Licence v3.0"
    }
  },
  "verification": {
    "uncertainty": {
      "basis": "published"
    }
  },
  "served_from": "edge",
  "served_version": "2026.180"
}

Changes

No recorded changes to this operation across all 1 revision of this API.