---
title: "Scope 2 electricity — location + market (dual reporting)"
method: POST
path: "/v1/calculate/electricity"
tags: ["Calculate"]
---

# Scope 2 electricity — location + market (dual reporting)

`POST /v1/calculate/electricity`

## Request

- Base URL: `https://api.greencalculus.com`
- URL: `https://api.greencalculus.com/v1/calculate/electricity`
- Auth: HTTP bearer

## Query parameters

- `as_of` string

## Request body

- object
  - `consumption` object, required: Electricity consumed.
    - `value` number
    - `unit` string: kWh | MWh | GWh
  - `location_factor_key` string, required
  - `market_factor_key` string: Optional. Market-based factor (e.g. residual mix) for dual reporting.
  - `supplier_factor` object: Optional contractual factor (green tariff / REC = 0). Wins over market_factor_key.
    - `value` number
    - `unit` string
  - `country` string: Optional. The country the ACTIVITY belongs to — ISO3, ISO2 or a name ("deu", "DE", "Germany"). When given, the response carries factor.resolution stating whether the factor used is published for that country (tier: exact), is a global figure applied to it (global), or belongs to a different country (proxy, with proxy_of naming which). Omit it and no geography claim is made — the response is unchanged. A country we do not recognise yields no claim rather than a wrong one.

## Response `200`

Location- and (if given) market-based emissions + working + source

- ElectricityCalculation: GHG Protocol Scope 2 — reports location-based and market-based SIDE BY SIDE, which is why this engine does not share the single-factor shape. market_based is null unless you supply a market instrument.
  - `methodology` string
  - `standard` string
  - `consumption` object
    - `value` number
    - `unit` string
    - `kwh` number: Normalised to kWh.
  - `location_based` object, nullable
    - `emissions` object
    - `method` string
    - `factor` object
    - `formula` string
  - `market_based` object, nullable: null when no market instrument was supplied — the absence of a market figure, not a zero.
  - `scope` object, nullable
  - `note` string, nullable
  - `meta` CalcMeta
    - `gc_version` string
    - `gc_updated` string
    - `reproducible` string: How to pin this result for an audit.
  - `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.
  - `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
- `422`: Unknown factor or incompatible units

---

[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)