Skip to main content
GET
/
v1
/
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));
{
  "toc": "<string>",
  "category": "<string>",
  "vehicle": "<string>",
  "type": "<string>",
  "wtw": 123,
  "default_load": 123,
  "location": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://code.dcycle.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Response

Returns an array of available vehicle types (TOCs) with their emission factors.
​
toc
string
Type of vehicle identifier (format: vehicle_type)
​
category
string
Transport category (road, rail, maritime, air)
​
vehicle
string
Vehicle type (e.g., van, rigid_truck, artic_truck, train, generic)
​
type
string
Detailed vehicle specification including fuel type, size, and other characteristics
​
wtw
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
​
default_load
number
Default load capacity in kg for this vehicle type. Used when no load is specified in the request.
​
location
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}"

​
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