Step 1: Track Transport Operations

Create transport legs, select TOCs, handle multi-modal shipments, and upload bulk data following GLEC v3.0

Understanding Transport Operations in GLEC

In the GLEC Framework, every shipment is broken down into transport legs — individual segments where goods move from one point to another using a specific vehicle type. Each leg is classified by its TOC (Transport Operation Category), which determines the emission factor applied.

┌──────────────────────────────────────────────────────────────────────────────┐
│                        TRANSPORT OPERATION FLOW                              │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Shipment: Madrid → Hamburg (multi-modal)                                   │
│                                                                              │
│  Leg 1 (Road)           Leg 2 (Maritime)         Leg 3 (Road)              │
│  ─────────────          ────────────────         ─────────────              │
│  Madrid → Barcelona     Barcelona → Hamburg      Hamburg → Warehouse        │
│  TOC: artic_truck       TOC: general_cargo       TOC: van_diesel           │
│  500 km · 12t           1800 km · 12t            30 km · 12t               │
│                                                                              │
│  CO2e = tkm × WTW      CO2e = tkm × WTW         CO2e = tkm × WTW         │
│                                                                              │
│  Total shipment CO2e = Leg 1 + Leg 2 + Leg 3                               │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

GLEC Calculation Formula

For each transport leg:

CO2e (kg) = tkm x WTW emission factor (kgCO2e/tkm)

Where:

• tkm = load (tonnes) x distance (km)
• WTW = Well-to-Wheel factor from the TOC (includes fuel production + combustion)
• For electric vehicles: CO2e = tkm x grid emission factor x energy efficiency factor

Prerequisites

Before starting, ensure you have:

• Dcycle API credentials (get them here)
• An organization configured in Dcycle
• Shipment data: origins, destinations, weights, and vehicle types (or at least transport category)

Step 1.1: Explore Available TOCs

Before creating transport legs, list the available vehicle types and their emission factors:

📋 Data Map: List TOCs

No input data required. Returns all available TOCs with their WTW factors and default loads.

Response fields:

Field	Description	Example
toc	Vehicle identifier (vehicle_type)	"van_diesel"
category	Transport mode	"road"
vehicle	Vehicle type	"van"
type	Fuel/specification	"diesel"
wtw	WTW factor (kgCO2e/tkm)	0.196
default_load	Default capacity (kg)	3500.0
location	Region	"EU"

Python

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
    "Content-Type": "application/json",
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "x-user-id": os.getenv("DCYCLE_USER_ID"),
}

# List all available TOCs
tocs = requests.get(
    "https://api.dcycle.io/v1/logistics/tocs",
    headers=headers,
).json()

print("Available Transport Operation Categories:")
for toc in tocs:
    print(f"  {toc['toc']:30s} | {toc['category']:10s} | WTW: {toc['wtw']:.4f} kgCO2e/tkm | Region: {toc['location']}")

Common TOCs by Transport Mode

Road

TOC	Vehicle	Fuel	Typical Use
van_diesel	Van	Diesel	Urban/last-mile deliveries
van_electric	Van	Electric	Zero-emission urban deliveries
rigid_truck_diesel	Rigid truck	Diesel	Regional freight
artic_truck_diesel	Articulated truck	Diesel	Long-haul freight
artic_truck_electric	Articulated truck	Electric	Electric long-haul
tank_truck_diesel	Tank truck	Diesel	Liquid bulk transport
generic_average_road	Generic	Average	When vehicle type is unknown

Road fuels supported: diesel, electric, CNG, LNG, HVO, biodiesel blends, LPG.

Rail

TOC	Vehicle	Typical Use
generic_average_rail	Generic freight train	Bulk goods, intermodal containers

Rail has the lowest emission intensity of land transport modes.

Maritime

TOC	Vehicle	Typical Use
oil_tanker_average_maritime	Oil tanker	Crude oil, petroleum products
general_cargo_average_maritime	General cargo	Break-bulk goods
bulk_carrier_average_maritime	Bulk carrier	Grain, coal, ore
ro_ro_average_maritime	Ro-Ro	Vehicles, wheeled cargo
generic_average_maritime	Generic	When vessel type is unknown

Air

TOC	Vehicle	Typical Use
freighter_average_air	Cargo freighter	Dedicated cargo aircraft
belly_freight_average_air	Belly freight	Cargo in passenger aircraft hold
generic_average_air	Generic	When aircraft type is unknown

Air freight has the highest emission intensity — typically 20-50x higher than maritime and 5-10x higher than road per tkm.

Don’t know the exact vehicle type? Provide only category (e.g., "road", "maritime") instead of toc, and Dcycle will use the generic average TOC for that mode and region.

Step 1.2: Create a Single Transport Leg

📋 Data Map: Create Transport Leg

Field	Type	Required	Description	Example
origin	string	Conditional	Origin address (required if no distance_km)	"Madrid, Spain"
destination	string	Conditional	Destination address (required if no distance_km)	"Barcelona, Spain"
distance_km	number	Conditional	Distance in km (used as-is, overrides geocoding)	620
toc	string	Conditional	TOC identifier (if omitted, provide category)	"rigid_truck_diesel"
category	string	Conditional	Transport mode (if toc is omitted)	"road"
origin_country	string	No	ISO 3166-2 code for region-specific factors	"ES"
load	number	No	Cargo weight (defaults to TOC’s default_load)	5000
load_unit	string	No	Unit: kg, ton, pallets, teu, feu	"kg"
load_factor	number	No	Allocation factor 0-1 (e.g., 0.5 = half truck)	0.5
year	number	No	Emission factor year (defaults to current)	2025
cleaning	boolean	No	Vehicle cleaning done (adds cleaning emissions)	false
subcontractor	boolean	No	Handled by a subcontractor (affects scope allocation)	false
client	string	No	Client identifier for reporting	"AMAZON"
movement_id	string	No	Groups multiple legs of the same shipment	"MOV-2025-001"
shipment_date	date	No	Date of shipment (YYYY-MM-DD)	"2025-03-15"
hub_id	string	No	Hub associated with this leg	"HUB-MAD-001"
package_key	string	No	Package identifier (requires movement_id)	"PKG-12345"

Where to get this data:

• toc: Use GET /v1/logistics/tocs to list available vehicle types
• origin/destination: Physical addresses or city names (geocoded automatically)
• load: From your shipping manifest, bill of lading, or TMS
• client: From your customer management system

Basic shipment (addresses + TOC)

Python

# Calculate a single road shipment
shipment = {
    "origin": "Calle Gran Via 1, Madrid, Spain",
    "destination": "Passeig de Gracia 50, Barcelona, Spain",
    "origin_country": "ES",
    "toc": "rigid_truck_diesel",
    "load": 8000,
    "load_unit": "kg",
    "year": 2025,
    "client": "RETAILCO",
    "shipment_date": "2025-03-15",
}

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

print(f"Request ID: {response['id']}")
print(f"Distance: {response['distance_km']:.1f} km (with DAF applied)")
print(f"CO2e: {response['co2e']:.2f} kg")
print(f"TOC: {response['toc']}")

Using known distance (skip geocoding)

When you already have the distance, provide distance_km directly:

# Known distance — geocoding is skipped
shipment = {
    "distance_km": 620,
    "origin_country": "ES",
    "toc": "artic_truck_diesel",
    "load": 15,
    "load_unit": "ton",
    "year": 2025,
}

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

print(f"CO2e: {response['co2e']:.2f} kg")

Using tkm directly

If you already know the tonne-kilometers, provide tkm:

# Known tkm — skip distance and load calculation
shipment = {
    "tkm": 9300,  # 15 tonnes x 620 km
    "origin_country": "ES",
    "toc": "artic_truck_diesel",
    "year": 2025,
}

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

Using category instead of TOC

When you don’t know the exact vehicle type:

# Only know it's road transport
shipment = {
    "origin": "Madrid, Spain",
    "destination": "Sevilla, Spain",
    "category": "road",  # Will use generic_average_road for the region
    "load": 3000,
    "load_unit": "kg",
}

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

print(f"TOC selected: {response['toc']}")
print(f"CO2e: {response['co2e']:.2f} kg")

Step 1.3: Multi-Modal and Multi-Leg Shipments

Use movement_id to group multiple legs into a single shipment, and package_key to track individual packages across legs:

movement_id = "MOV-2025-MAD-HAM-001"

# Leg 1: Road (first mile)
leg1 = {
    "origin": "Madrid, Spain",
    "destination": "Barcelona Port, Spain",
    "origin_country": "ES",
    "toc": "artic_truck_diesel",
    "load": 12000,
    "load_unit": "kg",
    "movement_id": movement_id,
    "movement_stretch": "first_mile",
    "package_key": "PKG-26830007899",
    "client": "IMPORT-CO",
}

# Leg 2: Maritime (main haul)
leg2 = {
    "origin": "Barcelona, Spain",
    "destination": "Hamburg, Germany",
    "origin_country": "ES",
    "toc": "general_cargo_average_maritime",
    "load": 12000,
    "load_unit": "kg",
    "movement_id": movement_id,
    "movement_stretch": "main_haul",
    "package_key": "PKG-26830007899",
    "client": "IMPORT-CO",
}

# Leg 3: Road (last mile)
leg3 = {
    "origin": "Hamburg Port, Germany",
    "destination": "Hamburg Warehouse, Germany",
    "origin_country": "DE",
    "toc": "van_diesel",
    "load": 12000,
    "load_unit": "kg",
    "movement_id": movement_id,
    "movement_stretch": "last_mile",
    "package_key": "PKG-26830007899",
    "client": "IMPORT-CO",
}

total_co2e = 0
for i, leg in enumerate([leg1, leg2, leg3], 1):
    result = requests.post(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        json=leg,
    ).json()
    total_co2e += result["co2e"]
    print(f"Leg {i} ({leg['movement_stretch']}): {result['co2e']:.2f} kg CO2e | {result['distance_km']:.0f} km")

print(f"\nTotal shipment CO2e: {total_co2e:.2f} kg")

Package tracking: When package_key is provided, Dcycle creates or updates a LogisticPackage that aggregates total_distance_km and total_co2e across all legs. Retrieve package details with GET /v1/logistics/packages/{package_id}.

Subcontracted Transport

Mark legs handled by a subcontractor. These emissions are classified as Scope 3 in the GLEC company report (instead of Scope 1 for own fleet):

subcontracted_leg = {
    "origin": "Madrid, Spain",
    "destination": "Lisbon, Portugal",
    "origin_country": "ES",
    "toc": "artic_truck_diesel",
    "load": 20,
    "load_unit": "ton",
    "subcontractor": True,  # Scope 3 in GLEC report
    "client": "CLIENTCO",
}

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

Own fleet vs Subcontracted — Scope allocation

	Own Fleet	Subcontracted
TTW (direct)	Scope 1	Scope 3
WTT (upstream)	Scope 3	Scope 3
Total WTW	Split Scope 1 + 3	Scope 3

Set subcontractor: true for any leg not operated by your own fleet.

Step 1.4: Load Units and Allocation

GLEC supports multiple load units. Dcycle converts them to kg internally:

Unit	Conversion	Typical Use
kg	1 kg	Default, most common
ton	1 ton = 1,000 kg	Heavy freight
pallets	1 pallet = 1,500 kg	Palletized goods
teu	1 TEU = 10,000 kg	Container shipping (20ft)
feu	1 FEU = 20,000 kg	Container shipping (40ft)

TEU and FEU use the GLEC Framework default of 10 tonnes of cargo per loaded TEU (GLEC v3.2, ISO 14083), not the container’s maximum weight. If you know the real cargo weight, send it in kg or ton instead.

Load Factor (Allocation)

Use load_factor to account for partial loads or shared capacity:

# Half-truck load
shipment = {
    "origin": "Madrid, Spain",
    "destination": "Valencia, Spain",
    "toc": "artic_truck_diesel",
    "load": 100,
    "load_unit": "pallets",
    "load_factor": 0.5,  # Only using 50% of capacity → 50 pallets
}

Step 1.5: Bulk Upload (Up to 5,000 Records)

For high-volume operations, use the bulk endpoint to process up to 5,000 transport legs in a single request:

📋 Data Map: Bulk Upload

Field	Type	Required	Description
records	array	Yes	Array of transport leg objects (same schema as single request)
options.continue_on_error	boolean	No	Continue processing if some records fail (default: true)

Each record in the records array uses the same fields as the single request in Step 1.2.

Python

# Bulk upload multiple transport legs
bulk_payload = {
    "records": [
        {
            "origin": "Madrid, Spain",
            "destination": "Barcelona, Spain",
            "toc": "rigid_truck_diesel",
            "load": 5000,
            "load_unit": "kg",
            "client": "CLIENT-A",
            "shipment_date": "2025-03-01",
        },
        {
            "origin": "Barcelona, Spain",
            "destination": "Valencia, Spain",
            "toc": "van_diesel",
            "load": 1200,
            "load_unit": "kg",
            "client": "CLIENT-A",
            "shipment_date": "2025-03-01",
        },
        {
            "origin": "Madrid, Spain",
            "destination": "Sevilla, Spain",
            "toc": "artic_truck_diesel",
            "load": 18,
            "load_unit": "ton",
            "client": "CLIENT-B",
            "shipment_date": "2025-03-02",
        },
    ],
    "options": {
        "continue_on_error": True,
    },
}

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

print(f"Total received: {response['total_received']}")
print(f"Success: {response['success']}")
print(f"Failed: {response['failed']}")

# Check individual results
for result in response["results"]:
    print(f"  Record {result['index']}: {result['co2e']:.2f} kg CO2e (ID: {result['id']})")

# Check errors
for error in response["errors"]:
    print(f"  Error at record {error['index']}: {error['error']}")

Bulk limits: Maximum 5,000 records per request. For larger datasets, split into multiple bulk requests or use the legacy CSV upload endpoint (POST /logistics/upload).

Step 1.6: Query Transport Requests

Retrieve your transport legs with pagination and filtering:

# Get paginated transport requests
response = requests.get(
    "https://api.dcycle.io/v1/logistics/requests",
    headers=headers,
    params={
        "page": 1,
        "size": 50,
    },
).json()

print(f"Total requests: {response['total']}")
for req in response["items"]:
    print(f"  {req['id'][:8]}... | {req['origin']} → {req['destination']} | {req['co2e']:.2f} kg CO2e")

Query Packages

Track multi-leg shipments via packages:

# Get all packages for a specific client
packages = requests.get(
    "https://api.dcycle.io/v1/logistics/packages",
    headers=headers,
    params={
        "client": "IMPORT-CO",
        "page": 1,
        "size": 50,
    },
).json()

for pkg in packages["items"]:
    print(f"Package {pkg['package_key']}: {pkg['total_co2e']:.2f} kg CO2e | {pkg['total_distance_km']:.0f} km")

# Get a single package with all its legs
package_detail = requests.get(
    f"https://api.dcycle.io/v1/logistics/packages/{packages['items'][0]['id']}",
    headers=headers,
).json()

print(f"\nPackage legs:")
for leg in package_detail["legs"]:
    print(f"  {leg['origin']} → {leg['destination']}: {leg['co2e']:.2f} kg CO2e")

List Clients

# Get all client names for the organization
clients = requests.get(
    "https://api.dcycle.io/v1/logistics/clients",
    headers=headers,
).json()

print("Clients with logistics data:")
for client_name in clients:
    print(f"  - {client_name}")

Best Practices

1. Choose the Most Specific TOC

More specific TOCs yield more accurate results:

Least accurate                                        Most accurate
generic_average_road  →  rigid_truck_diesel  →  rigid_truck_hvo_blend

When you know the fuel type and vehicle class, always use the specific TOC.

2. Provide Origin Country

Always include origin_country for region-specific emission factors:

# Without origin_country → uses GLO (global) factors
shipment = {"category": "road", "distance_km": 500, "load": 5000, "load_unit": "kg"}

# With origin_country → uses EU-specific factors (more accurate)
shipment = {"category": "road", "distance_km": 500, "load": 5000, "load_unit": "kg", "origin_country": "ES"}

3. Use Movement IDs Consistently

Group related legs with movement_id for accurate shipment-level reporting and deduplication.

4. Mark Subcontracted Legs

Always set subcontractor: true for legs not operated by your own fleet — this ensures correct scope allocation in the GLEC report.

Next Steps

Step 2: Hub Operations

Configure logistics hubs and track hub emissions

Step 4: GLEC Reports

Generate your GLEC company report