Skip to main content
POST
/
api
/
v1
/
logistics
/
shipment
Calculate Shipment
const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'x-user-id': '<x-user-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    origin: '<string>',
    destination: '<string>',
    toc: '<string>',
    load: 123,
    load_unit: '<string>',
    year: 123
  })
};

fetch('https://api.dcycle.io/api/v1/logistics/shipment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "co2e": 123,
  "distance_km": 123,
  "toc": "<string>",
  "load": 123,
  "load_unit": "<string>",
  "origin": "<string>",
  "destination": "<string>",
  "year": 123,
  "emission_factor": 123,
  "methodology": "<string>"
}

​
Calculate Shipment Emissions

Calculate CO2 equivalent (CO2e) emissions for a freight shipment. This endpoint follows ISO 14083 methodology for calculating transport emissions.
This endpoint calculates emissions but does not persist the shipment in the database. For bulk uploads that persist, use the CSV upload endpoint.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
​
x-user-id
string
required
Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Body Parameters

​
origin
string
required
Origin location of the shipment (city and country)Example: "Madrid, Spain"
​
destination
string
required
Destination location of the shipmentExample: "Barcelona, Spain"
​
toc
string
required
Transport type (Transport Operation Category)Possible values:
  • van_diesel - Diesel van
  • van_electric - Electric van
  • truck_diesel - Diesel truck
  • truck_articulated - Articulated truck
  • rail_freight - Freight train
  • air_freight - Cargo airplane
  • sea_container - Container ship
​
load
number
required
Transported load quantityExample: 1000
​
load_unit
string
required
Unit of measurement for the loadPossible values: kg, ton, m3, pallet
​
year
integer
Shipment year (default: current year)Example: 2024

​
Response

​
co2e
number
Total CO2 equivalent emissions in kilograms
​
distance_km
number
Calculated shipment distance in kilometers
​
toc
string
Transport type used
​
load
number
Transported load
​
load_unit
string
Load unit of measurement
​
origin
string
Shipment origin
​
destination
string
Shipment destination
​
year
integer
Shipment year
​
emission_factor
number
Emission factor used (kg CO2e per ton-km)
​
methodology
string
Methodology used for calculation (always “ISO 14083”)

​
Example

curl -X POST "https://api.dcycle.io/api/v1/logistics/shipment" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "Madrid, Spain",
    "destination": "Barcelona, Spain",
    "toc": "van_diesel",
    "load": 1000,
    "load_unit": "kg",
    "year": 2024
  }'

​
Successful Response

{
  "co2e": 245.5,
  "distance_km": 620.0,
  "toc": "van_diesel",
  "load": 1000,
  "load_unit": "kg",
  "origin": "Madrid, Spain",
  "destination": "Barcelona, Spain",
  "year": 2024,
  "emission_factor": 0.000396,
  "methodology": "ISO 14083"
}

​
Common Errors

​
400 Bad Request

Cause: Missing required parameters or incorrect format 
{
  "detail": "Field required",
  "code": "VALIDATION_ERROR",
  "field": "origin"
}
Solution: Verify that all required fields are present and correctly formatted.

​
422 Unprocessable Entity

Cause: Invalid transport type (toc) 
{
  "detail": "Invalid transport type",
  "code": "INVALID_TOC"
}
Solution: Use one of the valid values for toc: van_diesel, van_electric, truck_diesel, etc.

​
Use Cases

​
Quick Estimation

Use it to provide instant estimates to users before confirming a shipment: 
# Show estimate to user before confirming
estimate = calculate_shipment(origin, destination, load)
print(f"This shipment will generate {estimate['co2e']} kg of CO2e")

​
Comparing Options

Compare different transport modes: 
modes = ["van_diesel", "van_electric", "rail_freight"]
for mode in modes:
    result = calculate_shipment(origin, destination, load, toc=mode)
    print(f"{mode}: {result['co2e']} kg CO2e")

​
ISO 14083 Methodology

This endpoint implements the ISO 14083:2023 standard for quantification and reporting of GHG emissions in transport operations. Basic formula: 
CO2e = Distance (km) × Load (ton) × Emission Factor (kg CO2e/ton-km)
Emission factors are regularly updated based on:
  • GLEC Framework database
  • National country factors
  • Vehicle manufacturer data

Upload CSV

Bulk upload shipments

Get Clients

List your logistics clients

Get Report

Generate ISO 14083 report

Get TOCs

List available transport types