Calculate logistics emissions via API

POST /emissions/logistics creates a customer-attributed transport activity and applies an existing governed kgCO2e/tkm factor through deterministic tonne-km × factor calculation. Road, sea and air modes are accepted when the request supplies a supported, provenance-bearing distance.

The client sends customer_reference; it never sends an organization ID. Unknown references return CUSTOMER_NOT_FOUND and are never auto-created. The response exposes an opaque calculation ID, activity/emissions values, methodology boundary/version and safe factor source/version—not internal database identifiers.

Supported modes#

• ROAD
• AIR
• SEA

Each mode requires a positive distance in km, cargo in tonne, a valid activity date and an active governed kgCO2e/tkm factor reference. ErgOps does not invent distance or silently substitute a factor.

Request body#

{
  "customer_reference": "CUSTOMER-001",
  "external_reference": "SHIPMENT-93421",
  "mode": "ROAD",
  "origin": { "code": "GB-BHX", "country": "GB" },
  "destination": { "code": "GB-MAN", "country": "GB" },
  "cargo": { "value": 10, "unit": "tonne" },
  "distance": { "value": 550, "unit": "km" },
  "activity_date": "2026-09-27",
  "factor_reference": "YOUR_GOVERNED_FACTOR_KEY"
}

JavaScript#

const baseUrl = process.env.ERGOPS_BASE_URL;
const apiKey = process.env.ERGOPS_API_KEY;
const response = await fetch(`${baseUrl}/emissions/logistics`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Idempotency-Key": "shipment-93421", "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
const result = await response.json();

Python#

import os, requests
result = requests.post(
    f"{os.environ['ERGOPS_BASE_URL']}/emissions/logistics",
    headers={"Authorization": f"Bearer {os.environ['ERGOPS_API_KEY']}", "Idempotency-Key": "shipment-93421"},
    json=payload,
    timeout=30,
)
result.raise_for_status()
print(result.json())

Calculation result#

The deterministic formula is tonne-km × governed factor. Results use kgCO2e; the response includes activity value, factor source/version, boundary, methodology version and the public calculation identifier.