> ## 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

> Get a list of all available vehicle types (TOCs) for logistics calculations

# Get Available Vehicle Types

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

<Note>
  **New API**: This endpoint is part of the new API architecture with improved design and maintainability.
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

## Response

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

<ResponseField name="toc" type="string">
  Type of vehicle identifier (format: vehicle\_type)
</ResponseField>

<ResponseField name="category" type="string">
  Transport category (road, rail, maritime, air)
</ResponseField>

<ResponseField name="vehicle" type="string">
  Vehicle type (e.g., van, rigid\_truck, artic\_truck, train, generic)
</ResponseField>

<ResponseField name="type" type="string">
  Detailed vehicle specification including fuel type, size, and other characteristics
</ResponseField>

<ResponseField name="wtw" type="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`
</ResponseField>

<ResponseField name="default_load" type="number">
  Default load capacity in kg for this vehicle type. Used when no load is specified in the request.
</ResponseField>

<ResponseField name="location" type="string">
  Region where this emission factor applies: `EU` (Europe), `SA` (South America), `GLO` (Global/default)
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/logistics/tocs" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "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"
  }
]
```

<Note>
  **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.
</Note>

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

**Solution:** Verify your API key is valid and active. Get a new one from [Settings → API](https://app.dcycle.io/settings/api).

### 404 Not Found

**Cause:** Organization not found

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

<CardGroup cols={2}>
  <Card title="Road" icon="truck">
    Vans, rigid trucks, articulated trucks

    Examples: `van_3.5_t_diesel`, `artic_truck_up_to_40_t_gvw_average_diesel`
  </Card>

  <Card title="Rail" icon="train">
    Trains for various cargo types

    Examples: `train_container_electric`, `train_average_diesel`
  </Card>

  <Card title="Maritime" icon="ship">
    Container vessels, tankers, bulk carriers

    Examples: `average_container_vessel_dry`, `bulk_carrier_non_container_vessel_*`
  </Card>

  <Card title="Air" icon="plane">
    Air freight options

    Examples: `generic_average_air`, `air_freighter_long_haul_*`
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Logistics Request" icon="calculator" href="/api-reference/logistics/create-request">
    Calculate emissions using a TOC from this list
  </Card>

  <Card title="Get Logistics Requests" icon="list" href="/api-reference/logistics/get-requests">
    Retrieve all logistics requests with pagination
  </Card>

  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to get your API key
  </Card>
</CardGroup>