Get Available Vehicle Types

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/logistics/tocs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

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

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "toc": "<string>",
  "category": "<string>",
  "vehicle": "<string>",
  "type": "<string>",
  "wtw": 123,
  "default_load": 123,
  "location": "<string>"
}

GET

logistics

tocs

Get Available Vehicle Types

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/logistics/tocs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

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

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "toc": "<string>",
  "category": "<string>",
  "vehicle": "<string>",
  "type": "<string>",
  "wtw": 123,
  "default_load": 123,
  "location": "<string>"
}

Get Available Vehicle Types

Retrieve all available vehicle types (Types of Container - TOCs) that can be used for logistics emission calculations.

New API: This endpoint is part of the new API architecture with improved design and maintainability.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Response

Returns an array of available vehicle types (TOCs) with their emission factors.

string

Type of vehicle identifier (format: vehicle_type)

string

Transport category (road, rail, maritime, air)

string

Vehicle type (e.g., van, rigid_truck, artic_truck, train, generic)

string

Detailed vehicle specification including fuel type, size, and other characteristics

number

Well-to-Wheel emission factor in kgCO2e per tonne-kilometer (tkm). This is the factor used to calculate emissions: CO2e = load_tonnes × distance_km × wtw

number

Default load capacity in kg for this vehicle type. Used when no load is specified in the request.

string

Region where this emission factor applies: EU (Europe), SA (South America), GLO (Global/default)

Example

curl -X GET "https://api.dcycle.io/v1/logistics/tocs" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

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

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

response = requests.get(
    "https://api.dcycle.io/v1/logistics/tocs",
    headers=headers
)

tocs = response.json()
print(f"Available vehicle types: {len(tocs)}")
for toc in tocs[:3]:  # Show first 3
    print(f"  - {toc['toc']} ({toc['category']})")
    print(f"    Emission factor: {toc['wtw']} kgCO2e/tkm")
    print(f"    Default load: {toc['default_load']} kg")
    print(f"    Region: {toc['location']}")

const axios = require('axios');

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

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

axios.get(
  'https://api.dcycle.io/v1/logistics/tocs',
  { headers }
)
.then(response => {
  console.log(`Available vehicle types: ${response.data.length}`);
  response.data.slice(0, 3).forEach(toc => {
    console.log(`  - ${toc.toc} (${toc.category})`);
    console.log(`    Emission factor: ${toc.wtw} kgCO2e/tkm`);
    console.log(`    Default load: ${toc.default_load} kg`);
    console.log(`    Region: ${toc.location}`);
  });
})
.catch(error => console.error(error));

Successful Response

[
  {
    "toc": "van_3.5_t_diesel",
    "category": "road",
    "vehicle": "van",
    "type": "3.5_t_diesel",
    "wtw": 0.196,
    "default_load": 3500.0,
    "location": "EU"
  },
  {
    "toc": "van_3.5_t_electricity",
    "category": "road",
    "vehicle": "van",
    "type": "3.5_t_electricity",
    "wtw": 0.0,
    "default_load": 3500.0,
    "location": "EU"
  },
  {
    "toc": "rigid_truck_7.5_12_t_gvw_average_diesel",
    "category": "road",
    "vehicle": "rigid_truck",
    "type": "7.5_12_t_gvw_average_diesel",
    "wtw": 0.091,
    "default_load": 7500.0,
    "location": "EU"
  },
  {
    "toc": "artic_truck_up_to_40_t_gvw_average_diesel",
    "category": "road",
    "vehicle": "artic_truck",
    "type": "up_to_40_t_gvw_average_diesel",
    "wtw": 0.058,
    "default_load": 21500.0,
    "location": "EU"
  },
  {
    "toc": "train_average_electric",
    "category": "rail",
    "vehicle": "train",
    "type": "average_electric",
    "wtw": 0.018,
    "default_load": 500000.0,
    "location": "EU"
  },
  {
    "toc": "generic_average_maritime",
    "category": "maritime",
    "vehicle": "generic",
    "type": "average_maritime",
    "wtw": 0.016,
    "default_load": 10000000.0,
    "location": "GLO"
  },
  {
    "toc": "generic_average_air",
    "category": "air",
    "vehicle": "generic",
    "type": "average_air",
    "wtw": 1.128,
    "default_load": 50000.0,
    "location": "GLO"
  }
]

Understanding the emission factor (wtw): The Well-to-Wheel emission factor represents the total CO2e emissions per tonne-kilometer, including fuel production and combustion. Electric vehicles show wtw: 0.0 because grid emissions are accounted for separately.

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active. Get a new one from Settings → API.

404 Not Found

Cause: Organization not found

{
  "code": "ORGANIZATION_NOT_FOUND",
  "detail": "Organization with id=UUID('...') not found"
}

Solution: Verify that the x-organization-id header contains a valid organization UUID.

Use Cases

List All Available Vehicle Types

Get all available TOCs to present options to users:

def get_vehicle_types():
    """Retrieve all available vehicle types grouped by category"""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/tocs",
        headers=headers
    )

    tocs = response.json()

    # Group by category with emission factors
    by_category = {}
    for toc in tocs:
        category = toc['category']
        if category not in by_category:
            by_category[category] = []
        by_category[category].append({
            'toc': toc['toc'],
            'wtw': toc['wtw'],
            'location': toc['location']
        })

    return by_category

# Example usage
vehicle_types = get_vehicle_types()
print(f"Road vehicles: {len(vehicle_types['road'])}")
print(f"Rail vehicles: {len(vehicle_types['rail'])}")
print(f"Maritime vessels: {len(vehicle_types['maritime'])}")
print(f"Air transport: {len(vehicle_types['air'])}")

Calculate Emissions Manually

Use the emission factor to understand or verify calculations:

def calculate_emissions(toc_data, load_kg, distance_km):
    """
    Calculate CO2e emissions using the TOC emission factor.

    Formula: CO2e = load_tonnes × distance_km × wtw
    """
    load_tonnes = load_kg / 1000
    wtw = toc_data['wtw']

    co2e_kg = load_tonnes * distance_km * wtw

    return {
        'co2e_kg': co2e_kg,
        'formula': f"{load_tonnes} t × {distance_km} km × {wtw} = {co2e_kg:.4f} kgCO2e"
    }

# Example: 1000 kg shipment, 500 km distance, using van diesel
response = requests.get("https://api.dcycle.io/v1/logistics/tocs", headers=headers)
tocs = response.json()

# Find van diesel TOC
van_diesel = next(t for t in tocs if t['toc'] == 'van_3.5_t_diesel')
result = calculate_emissions(van_diesel, load_kg=1000, distance_km=500)
print(result['formula'])  # 1.0 t × 500 km × 0.196 = 98.0000 kgCO2e

Filter by Category

Filter TOCs by transport category:

def get_tocs_by_category(category):
    """Get vehicle types for a specific transport category"""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/tocs",
        headers=headers
    )

    tocs = response.json()
    return [toc['toc'] for toc in tocs if toc['category'] == category]

# Example: Get all road vehicle types
road_vehicles = get_tocs_by_category('road')
print(f"Available road vehicles: {road_vehicles[:5]}")

Build a Vehicle Selector

Use TOCs to build a dropdown for shipment calculations with emission factor visibility:

def create_vehicle_selector():
    """Create a formatted list of vehicle options with emission factors"""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/tocs",
        headers=headers
    )

    tocs = response.json()

    options = []
    for toc in tocs:
        # Format: "Van 3.5t Diesel (0.196 kgCO2e/tkm) - EU"
        label = f"{toc['vehicle'].replace('_', ' ').title()} {toc['type'].replace('_', ' ')}"
        if toc['wtw']:
            label += f" ({toc['wtw']} kgCO2e/tkm)"
        label += f" - {toc['location']}"

        options.append({
            'value': toc['toc'],
            'label': label,
            'category': toc['category'],
            'wtw': toc['wtw'],
            'default_load': toc['default_load'],
            'location': toc['location']
        })

    return options

# Use in your UI - users can see emission factors when selecting vehicles
vehicle_options = create_vehicle_selector()

Vehicle Type Categories

The endpoint returns TOCs across four transport categories:

Road

Vans, rigid trucks, articulated trucksExamples: van_3.5_t_diesel, artic_truck_up_to_40_t_gvw_average_diesel

Rail

Trains for various cargo typesExamples: train_container_electric, train_average_diesel

Maritime

Container vessels, tankers, bulk carriersExamples: average_container_vessel_dry, bulk_carrier_non_container_vessel_*

Air

Air freight optionsExamples: generic_average_air, air_freighter_long_haul_*

Create Logistics Request

Calculate emissions using a TOC from this list

Get Logistics Requests

Retrieve all logistics requests with pagination

Authentication Guide

Learn how to get your API key

​Get Available Vehicle Types

​Request

​Headers

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​Use Cases

​List All Available Vehicle Types

​Calculate Emissions Manually

​Filter by Category

​Build a Vehicle Selector

​Vehicle Type Categories

Road

Rail

Maritime

Air

​Related Endpoints

Create Logistics Request

Get Logistics Requests

Authentication Guide

Get Available Vehicle Types

Request

Headers

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

Use Cases

List All Available Vehicle Types

Calculate Emissions Manually

Filter by Category

Build a Vehicle Selector

Vehicle Type Categories

Related Endpoints