---
title: "Whole-life embodied carbon (EN 15978 modular, boundary-aware)"
method: POST
path: "/v1/calculate/embodied"
tags: ["Calculate"]
---

# Whole-life embodied carbon (EN 15978 modular, boundary-aware)

`POST /v1/calculate/embodied`

## Request

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

Version pinning is NOT available on this engine: the pin resolves keys named `*factor_key`, and this endpoint is addressed by `material_key` (and its per-module rows). Sending ?as_of= here is a 400 rather than a silent fall back to current data — a calculation that carries a receipt has to be the version it claims.

## Request body

- object
  - `materials` object[], required
    - `material_key` string
    - `quantity` object
      - `value` number
      - `unit` string
    - `boundary` 'A1-A3' | 'A1-A4' | 'A1-A5' | 'A1-C'
    - `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.
  - `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`

Per-stage embodied carbon + boundary total; module D separate; data gaps flagged

- EmbodiedCalculation: Whole-life embodied carbon, EN 15978 modular. Per-material and per-module, with data gaps declared rather than silently zeroed.
  - `methodology` string
  - `standard` string
  - `result` object
    - `total_embodied_carbon` object
    - `materials_count` integer
    - `has_data_gaps` boolean: true where a module carries no factor. The gap is declared, never treated as zero.
  - `materials` object[]
    - `id` unknown
    - `material_key` string
    - `material` unknown
    - `quantity` object
    - `boundary` string: The EN 15978 modules this figure covers.
    - `embodied_carbon` object
    - `stages` object[]: Per EN 15978 life-cycle stage. `in_boundary` says whether the stage counts toward this result — a stage OUTSIDE the boundary is still reported, with its value, rather than hidden.
      - `stage` string
      - `value` number
      - `unit` string
      - `in_boundary` boolean
      - `modules` string[]
    - `module_d` unknown
    - `gaps` unknown
    - `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
  - `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.

---

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