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

import requests

url = "https://api.dcycle.io/api/v1/logistics/shipment"

payload = {
    "origin": "<string>",
    "destination": "<string>",
    "toc": "<string>",
    "load": 123,
    "load_unit": "<string>",
    "year": 123
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "x-user-id": "<x-user-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/api/v1/logistics/shipment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "origin": "<string>",
  "destination": "<string>",
  "toc": "<string>",
  "load": 123,
  "load_unit": "<string>",
  "year": 123
}
'

{
  "co2e": 123,
  "distance_km": 123,
  "toc": "<string>",
  "load": 123,
  "load_unit": "<string>",
  "origin": "<string>",
  "destination": "<string>",
  "year": 123,
  "emission_factor": 123,
  "methodology": "<string>"
}

POST

api

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

import requests

url = "https://api.dcycle.io/api/v1/logistics/shipment"

payload = {
    "origin": "<string>",
    "destination": "<string>",
    "toc": "<string>",
    "load": 123,
    "load_unit": "<string>",
    "year": 123
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "x-user-id": "<x-user-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/api/v1/logistics/shipment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "origin": "<string>",
  "destination": "<string>",
  "toc": "<string>",
  "load": 123,
  "load_unit": "<string>",
  "year": 123
}
'

{
  "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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Body Parameters

string

required

Origin location of the shipment (city and country)Example: "Madrid, Spain"

string

required

Destination location of the shipmentExample: "Barcelona, Spain"

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

number

required

Transported load quantityExample: 1000

string

required

Unit of measurement for the loadPossible values: kg, ton, m3, pallet

integer

Shipment year (default: current year)Example: 2024

Response

number

Total CO2 equivalent emissions in kilograms

number

Calculated shipment distance in kilometers

string

Transport type used

number

Transported load

string

Load unit of measurement

string

Shipment origin

string

Shipment destination

integer

Shipment year

number

Emission factor used (kg CO2e per ton-km)

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
  }'

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "Authorization": f"Bearer {api_key}",
    "x-organization-id": org_id,
    "x-user-id": user_id,
    "Content-Type": "application/json"
}

payload = {
    "origin": "Madrid, Spain",
    "destination": "Barcelona, Spain",
    "toc": "van_diesel",
    "load": 1000,
    "load_unit": "kg",
    "year": 2024
}

response = requests.post(
    "https://api.dcycle.io/api/v1/logistics/shipment",
    headers=headers,
    json=payload
)

result = response.json()
print(f"CO2e: {result['co2e']} kg")
print(f"Distance: {result['distance_km']} km")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'x-organization-id': orgId,
  'x-user-id': userId,
  'Content-Type': 'application/json'
};

const payload = {
  origin: "Madrid, Spain",
  destination: "Barcelona, Spain",
  toc: "van_diesel",
  load: 1000,
  load_unit: "kg",
  year: 2024
};

axios.post(
  'https://api.dcycle.io/api/v1/logistics/shipment',
  payload,
  { headers }
)
.then(response => {
  console.log(`CO2e: ${response.data.co2e} kg`);
  console.log(`Distance: ${response.data.distance_km} km`);
})
.catch(error => console.error(error));

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

API Introduction Upload CSV

Introduction

Logistics

Facilities

Vehicles

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

Calculate Shipment

Calculate Shipment Emissions

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

400 Bad Request

422 Unprocessable Entity

Use Cases

Quick Estimation

Comparing Options

ISO 14083 Methodology

Upload CSV

Get Clients

Get Report

Get TOCs

​Calculate Shipment Emissions

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​400 Bad Request

​422 Unprocessable Entity

​Use Cases

​Quick Estimation

​Comparing Options

​ISO 14083 Methodology

​Related Endpoints

Upload CSV

Get Clients

Get Report

Get TOCs

Calculate Shipment Emissions

Request

Headers

Body Parameters

Response

Example

Successful Response

Common Errors

400 Bad Request

422 Unprocessable Entity

Use Cases

Quick Estimation

Comparing Options

ISO 14083 Methodology

Related Endpoints