---
title: "Freight (GLEC) — the factor's denominator picks the method: mass × distance (tonne-km) or TEU × distance (TEU-km)"
method: POST
path: "/v1/calculate/freight"
tags: ["Calculate"]
---

# Freight (GLEC) — the factor's denominator picks the method: mass × distance (tonne-km) or TEU × distance (TEU-km)

`POST /v1/calculate/freight`

## Request

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

Send `mass` for a factor denominated per tonne-km, `teu` for one denominated per TEU-km (the sea-container family — a TEU is a twenty-foot container slot, not a mass). Sending the wrong one is refused with 422 `gc_freight_basis_mismatch` rather than silently multiplied.

## Query parameters

- `as_of` string

## Request body

- object
  - `mass` object: Required for a per-tonne-km factor. Mutually exclusive with teu.
    - `value` number
    - `unit` string
  - `teu` object: Required for a per-TEU-km factor (container shipping). A forty-foot box is 2 TEU. Mutually exclusive with mass.
    - `value` number
    - `unit` string
  - `distance` object, required
    - `value` number
    - `unit` string
  - `factor_key` string, required
  - `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`

Tonne-km or TEU-km emissions + working + source

- Calculation: The SINGLE-FACTOR engines — ghg-activity, freight, spend-based and business-travel. The full working, never just a total. The block echoing your input is named per engine (activity | transport | spend | trip); everything else below is shared. The other four engines answer a different question and have their own schemas: ElectricityCalculation, PcafCalculation, EmbodiedCalculation, BatchCalculation.
  - `methodology` string
  - `standard` string
  - `emissions` object
    - `value` number
    - `unit` string
    - `range` object, nullable: Propagated from the factor's published uncertainty. null where the publisher states none — not a claim of certainty.
  - `activity` object: ghg-activity only. freight sends `transport`, spend-based `spend`, business-travel `trip`.
  - `factor` object
    - `key` string
    - `name` string, nullable
    - `value` number
    - `unit` string
    - `gas` string, nullable
    - `gwp_set` 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%".
    - `citation` Citation: A ready-to-paste citation assembled from the source registry.
      - `text` string
      - `source_id` string
      - `source_name` string
      - `cell_ref` string
      - `licence` string
      - `mb_version` string
      - `url` string
    - `resolution` object: Present ONLY when the request sent `country`. tier is exact | global | proxy; proxy_of names the country the factor actually belongs to. Absent means no geography claim was made — NOT that the match was exact.
      - `tier` string
      - `proxy_of` string, nullable
  - `scope` object, nullable
  - `working` object: The arithmetic in the open — unit conversion and the formula as evaluated.
    - `unit_conversion` string
    - `formula` string
  - `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
  - `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 the activity input does not match the factor's denominator

---

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