Get CO₂e for a complete run

Description

This endpoint computes CO₂e emissions for a complete road collection and delivery operation, also known as a milk run. Total emissions are first calculated for the full vehicle run (considering weight, distance, and load factor), then allocated across shipments according to their transport activity, following ISO 14083 principles.

Input overview

The endpoint takes as input:

• locations: the ordered sequence of stops in the run
• orders: the shipments carried, each referencing stop indices
• details: vehicle characteristics (fuel type, truck size)
• metadata: any custom key-value pairs, returned as-is in the response

Locations & terminal handling

• A run is the full itinerary taken by the vehicle.
• Locations can be expressed as UNLOCODE strings (e.g. "FRMRS") or as "longitude,latitude" coordinates (e.g. "8.833,53.884").
• The order in the list determines each stop's index, starting at 0.

Three run shapes are supported:

Open loop: the vehicle does not return to its starting point:

"locations": ["FRMRS", "FRVAF", "FRLIO"]

Closed loop: the vehicle returns to its starting point; repeat the first location at the end:

"locations": ["FRMRS", "FRVAF", "FRLIO", "FRMRS"]

Unknown terminal: the depot is unknown; use "" as a placeholder for the first and last stops. The API infers a truck terminal to represent vehicle repositioning. Indices start at the first element, even when it is empty:

"locations": ["", "FRMRS", "FRVAF", "FRLIO", ""]

The inferred terminal behaves like a standard location: legs connected to it may be empty or loaded, and empty running only occurs when no shipment is assigned to them.

Orders

Each order represents a parcel transported from one stop to another. Orders must cover all goods moved during the run. The endpoint takes as input:

• fromIndex: index of the pickup stop
• toIndex: index of the delivery stop
• weight: weight in kilograms
• id: optional identifier, returned in the response
• type: must be "PARCEL"

Example: a 1,500 kg shipment picked up at index 1 (FRMRS) and delivered at index 4 (FRVAF):

{
  "fromIndex": 1,
  "toIndex": 4,
  "weight": 1500,
  "id": "ABC123",
  "type": "PARCEL"
}

Methodology

Full run emissions

The Run API models emissions for the complete vehicle run, using:

• road network distances between successive locations,
• vehicle characteristics (fuel, size),
• load evolution along the route,
• empty and loaded movements.

Shipment allocation (ISO 14083)

Emissions are allocated based on transport activity (weight * pickup-to-delivery distance). Allocation depends on each shipment's pickup and delivery locations. Great circle distances are used for computing transport activities.

Response

The response contains:

• co2e: total emissions in grams for the entire run, split into WTT and TTW.
• orders: CO2e allocation per order, including intensity, allocation percentage, distance.
• parameters: the resolved run definition (locations with indices, vehicle details).
• properties: computation details: allocation method, data type, total distance, empty running ratio, and per-leg properties (distance, region, load factor).

Notes & considerations

• Details (vehicle): vehicle characteristics can be optionally passed. If omitted, the API defaults to DIESEL fuel and selects the smallest truck size that can carry the orders (4t to 60t GVW).
• Metadata: any value added to the metadata object is returned unchanged in the response. It has no effect on the CO2e calculation.
• Empty running: occurs whenever the vehicle travels without any assigned shipment (not configured manually). Empty legs are included in total vehicle emissions, and loadFactor = 0 identifies empty running segments in the response. Note that terminal legs are not automatically empty, it depends on the orders passed.
• ISO 14083 alignment: the allocation method and emission calculations follow the ISO 14083 standard.

Support endpoints and resources

For a detailed information about the Milk Run methodology, refer to our Guides section.