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

# Transport Types

> Get the list of available transport types (TOCs)

# Transport Types (TOCs)

Get the complete list of supported transport types (Transport Operation Categories) with their emission factors.

<Info>
  TOC (Transport Operation Category) is the ISO 14083 standard term for classifying transport modes by vehicle type, fuel, and capacity.
</Info>

## 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:** `ff4adcc7-8172-45fe-9cf1-e90a6de53aa9`
</ParamField>

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

  **Example:** `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
</ParamField>

This endpoint requires no parameters.

## Response

Returns an array of objects with information about each transport type:

<ResponseField name="toc_id" type="string">
  Unique identifier for the transport type (use it in other endpoints)
</ResponseField>

<ResponseField name="name" type="string">
  Descriptive name of the transport type
</ResponseField>

<ResponseField name="category" type="string">
  General category: `road`, `rail`, `air`, `sea`
</ResponseField>

<ResponseField name="vehicle_type" type="string">
  Vehicle type: `van`, `truck`, `train`, `airplane`, `ship`
</ResponseField>

<ResponseField name="fuel_type" type="string">
  Fuel type: `diesel`, `electric`, `petrol`, `lng`, `aviation_fuel`, `marine_fuel`
</ResponseField>

<ResponseField name="emission_factor" type="number">
  Emission factor in kg CO2e per ton-km
</ResponseField>

<ResponseField name="capacity" type="string">
  Typical vehicle capacity
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/api/v1/logistics/tocs" \
    -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "x-user-id: ${DCYCLE_USER_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 = {
      "Authorization": f"Bearer {api_key}",
      "x-organization-id": org_id,
      "x-user-id": user_id
  }

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

  tocs = response.json()
  for toc in tocs:
      print(f"{toc['toc_id']}: {toc['name']} ({toc['emission_factor']} kg CO2e/ton-km)")
  ```

  ```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 = {
    'Authorization': `Bearer ${apiKey}`,
    'x-organization-id': orgId,
    'x-user-id': userId
  };

  axios.get(
    'https://api.dcycle.io/api/v1/logistics/tocs',
    { headers }
  )
  .then(response => {
    response.data.forEach(toc => {
      console.log(`${toc.toc_id}: ${toc.name} (${toc.emission_factor} kg CO2e/ton-km)`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "toc_id": "van_diesel",
    "name": "Diesel Van",
    "category": "road",
    "vehicle_type": "van",
    "fuel_type": "diesel",
    "emission_factor": 0.000396,
    "capacity": "< 3.5 ton"
  },
  {
    "toc_id": "van_electric",
    "name": "Electric Van",
    "category": "road",
    "vehicle_type": "van",
    "fuel_type": "electric",
    "emission_factor": 0.000098,
    "capacity": "< 3.5 ton"
  },
  {
    "toc_id": "truck_diesel",
    "name": "Diesel Rigid Truck",
    "category": "road",
    "vehicle_type": "truck",
    "fuel_type": "diesel",
    "emission_factor": 0.000512,
    "capacity": "3.5 - 7.5 ton"
  },
  {
    "toc_id": "truck_articulated",
    "name": "Articulated Truck",
    "category": "road",
    "vehicle_type": "truck",
    "fuel_type": "diesel",
    "emission_factor": 0.000673,
    "capacity": "> 33 ton"
  },
  {
    "toc_id": "rail_freight",
    "name": "Freight Train",
    "category": "rail",
    "vehicle_type": "train",
    "fuel_type": "electric",
    "emission_factor": 0.000025,
    "capacity": "High capacity"
  },
  {
    "toc_id": "air_freight",
    "name": "Cargo Airplane",
    "category": "air",
    "vehicle_type": "airplane",
    "fuel_type": "aviation_fuel",
    "emission_factor": 0.00245,
    "capacity": "Variable"
  },
  {
    "toc_id": "sea_container",
    "name": "Container Ship",
    "category": "sea",
    "vehicle_type": "ship",
    "fuel_type": "marine_fuel",
    "emission_factor": 0.000012,
    "capacity": "Very high capacity"
  }
]
```

## Use Cases

### Transport Type Selector

Populate a selector in your UI with available types:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_transport_options():
    """Get transport options for selector"""
    tocs = get_tocs()

    # Group by category
    by_category = {}
    for toc in tocs:
        category = toc['category']
        if category not in by_category:
            by_category[category] = []
        by_category[category].append({
            'value': toc['toc_id'],
            'label': toc['name'],
            'emissions': toc['emission_factor']
        })

    return by_category

# Result:
# {
#   "road": [{"value": "van_diesel", "label": "Diesel Van", ...}],
#   "rail": [...],
#   "air": [...],
#   "sea": [...]
# }
```

### Emissions Comparator

Compare emission factors between different modes:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def compare_transport_modes():
    """Compare emissions by transport mode"""
    tocs = get_tocs()

    # Sort by emission factor (lowest to highest)
    sorted_tocs = sorted(tocs, key=lambda x: x['emission_factor'])

    print("🌿 Transport modes sorted by emissions (lowest to highest):\n")

    for i, toc in enumerate(sorted_tocs, 1):
        print(f"{i}. {toc['name']}")
        print(f"   Factor: {toc['emission_factor']} kg CO2e/ton-km")
        print(f"   Category: {toc['category']}\n")

# Output:
# 1. Container Ship
#    Factor: 0.000012 kg CO2e/ton-km
#    Category: sea
#
# 2. Freight Train
#    Factor: 0.000025 kg CO2e/ton-km
#    Category: rail
# ...
```

### Impact Calculator

Calculate the impact of switching transport modes:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def calculate_mode_switch_impact(distance_km, load_kg, from_toc, to_toc):
    """Calculate impact of switching transport modes"""
    tocs = {toc['toc_id']: toc for toc in get_tocs()}

    load_ton = load_kg / 1000
    ton_km = distance_km * load_ton

    # Emissions with current mode
    current_emissions = ton_km * tocs[from_toc]['emission_factor']

    # Emissions with alternative mode
    new_emissions = ton_km * tocs[to_toc]['emission_factor']

    # Savings
    savings = current_emissions - new_emissions
    savings_percentage = (savings / current_emissions) * 100

    return {
        'current_mode': tocs[from_toc]['name'],
        'new_mode': tocs[to_toc]['name'],
        'current_emissions': current_emissions,
        'new_emissions': new_emissions,
        'savings_kg': savings,
        'savings_percentage': savings_percentage
    }

# Example: Switch from diesel truck to train
impact = calculate_mode_switch_impact(
    distance_km=500,
    load_kg=5000,
    from_toc='truck_diesel',
    to_toc='rail_freight'
)

print(f"Switching from {impact['current_mode']} to {impact['new_mode']}:")
print(f"Savings: {impact['savings_kg']:.2f} kg CO2e ({impact['savings_percentage']:.1f}%)")
```

### Data Validation

Validate that a TOC exists before calculating:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def validate_toc(toc_id):
    """Validate that a TOC exists"""
    tocs = get_tocs()
    valid_toc_ids = [toc['toc_id'] for toc in tocs]

    if toc_id not in valid_toc_ids:
        raise ValueError(
            f"TOC '{toc_id}' not valid. "
            f"Valid options: {', '.join(valid_toc_ids)}"
        )

    return True
```

## Filtering by Category

While the endpoint doesn't support filters directly, you can filter in your code:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Get only road transport
road_tocs = [toc for toc in get_tocs() if toc['category'] == 'road']

# Get only electric vehicles
electric_tocs = [toc for toc in get_tocs() if toc['fuel_type'] == 'electric']

# Get TOCs with low emissions (< 0.0001 kg/ton-km)
low_emission_tocs = [toc for toc in get_tocs() if toc['emission_factor'] < 0.0001]
```

## Emission Factors

Emission factors are based on:

* **GLEC Framework** - Global Logistics Emissions Council
* **EN 16258** - European standard for transport emissions
* **DEFRA** - UK Government conversion factors
* **EPA** - US Environmental Protection Agency

<Note>
  Emission factors are updated annually to reflect the latest methodologies and available data.
</Note>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Calculate Shipment" icon="calculator" href="/api-docs/logistics/calculate-shipment">
    Use a TOC to calculate emissions
  </Card>

  <Card title="Upload CSV" icon="upload" href="/api-docs/logistics/upload-csv">
    Specify TOCs in your CSV
  </Card>
</CardGroup>