← Logistics APIRetrieve all available vehicle types (Types of Container - TOCs) that can be used for logistics emission calculations.
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)
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: The key is invalid or revoked (INVALID_API_KEY), expired (API_KEY_EXPIRED), belongs neither to the
organization in x-organization-id nor to one of its parents (API_KEY_ORG_MISMATCH, whether or not that organization
exists), or has no owner (API_KEY_NO_OWNER). A request carrying no credentials at all answers
AUTHENTICATION_REQUIRED. See Errors.
{ "detail": "Invalid API key", "code": "INVALID_API_KEY"}
Solution: Verify your API key is valid and active. Get a new one in Company settings → API Keys.
For API_KEY_ORG_MISMATCH, send the id of the key’s organization or of one of its subsidiaries.
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 usagevehicle_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 dieselresponse = requests.get("https://api.dcycle.io/v1/logistics/tocs", headers=headers)tocs = response.json()# Find van diesel TOCvan_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 typesroad_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 vehiclesvehicle_options = create_vehicle_selector()
Vehicle Type Categories
The endpoint returns TOCs across four transport categories: