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

# List Unknown Vehicles

> Retrieve all available vehicle type classifications

# List Unknown Vehicles

Retrieve all available vehicle type classifications in the system. Each type includes region-specific information and can be used when creating vehicles in your fleet.

<Note>
  **Reference Data**: This endpoint returns standardized vehicle type classifications used across the platform. Use the vehicle type IDs returned here when creating vehicles with the `unknown_vehicle_id` parameter.
</Note>

## Request

### Headers

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

  **Format:** Your API key string
</ParamField>

## Response

<ResponseField name="array" type="array[object]">
  Array of vehicle type objects

  <Expandable title="Vehicle Type Object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID) for the vehicle type
    </ResponseField>

    <ResponseField name="type" type="string">
      Vehicle type name (e.g., "van", "truck", "car", "suv")
    </ResponseField>

    <ResponseField name="country" type="string">
      ISO 3166-1 two-letter country code for emission factors
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Timestamp when the vehicle type was created
    </ResponseField>

    <ResponseField name="updated_at" type="datetime | null">
      Timestamp when the vehicle type was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

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

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  api_key = os.getenv("DCYCLE_API_KEY")

  headers = {
      "x-api-key": api_key
  }

  response = requests.get(
      "https://api.dcycle.io/v1/unknown-vehicles",
      headers=headers
  )

  vehicles = response.json()
  for vehicle in vehicles:
      print(f"{vehicle['type']} ({vehicle['country']}): {vehicle['id']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const apiKey = process.env.DCYCLE_API_KEY;

  const headers = {
    'x-api-key': apiKey
  };

  axios.get(
    'https://api.dcycle.io/v1/unknown-vehicles',
    { headers }
  )
  .then(response => {
    response.data.forEach(vehicle => {
      console.log(`${vehicle.type} (${vehicle.country}): ${vehicle.id}`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "van",
    "country": "ES",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "truck",
    "country": "ES",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "type": "car",
    "country": "ES",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "type": "suv",
    "country": "ES",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440004",
    "type": "motorcycle",
    "country": "ES",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]
```

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

### 500 Internal Server Error

**Cause:** Server error retrieving vehicle type data

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Internal server error",
  "code": "INTERNAL_ERROR"
}
```

**Solution:** Contact support if the error persists.

## Use Cases

### Get All Vehicle Types for Vehicle Creation

Retrieve available types before creating a vehicle:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_all_vehicle_types():
    """Get all available vehicle types"""
    response = requests.get(
        "https://api.dcycle.io/v1/unknown-vehicles",
        headers=headers
    )

    return response.json()

# Get all types
all_types = get_all_vehicle_types()
print(f"Available vehicle types: {len(all_types)}")

# Find a specific type
van = next(v for v in all_types if v['type'] == 'van')
print(f"Van ID: {van['id']}")
```

### Filter Vehicle Types by Country

Get vehicle types specific to a country:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_vehicle_types_by_country(country_code):
    """Get vehicle types for a specific country"""
    response = requests.get(
        "https://api.dcycle.io/v1/unknown-vehicles",
        headers=headers
    )

    vehicles = response.json()
    country_vehicles = [v for v in vehicles if v['country'] == country_code]

    return country_vehicles

# Get vehicle types for Spain
spain_vehicles = get_vehicle_types_by_country("ES")
print("Available vehicle types in Spain:")
for v in spain_vehicles:
    print(f"  - {v['type']}")
```

### Group Vehicle Types by Name

Organize vehicle types for display:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def group_vehicle_types_by_name():
    """Group all vehicle types by type name"""
    response = requests.get(
        "https://api.dcycle.io/v1/unknown-vehicles",
        headers=headers
    )

    vehicles = response.json()
    grouped = {}

    for vehicle in vehicles:
        vehicle_type = vehicle['type']
        if vehicle_type not in grouped:
            grouped[vehicle_type] = []
        grouped[vehicle_type].append({
            "id": vehicle['id'],
            "country": vehicle['country']
        })

    return grouped

# Get grouped types
types_by_name = group_vehicle_types_by_name()
for type_name, entries in types_by_name.items():
    print(f"{type_name}: {len(entries)} countries")
```

### Create Vehicle Type Selection Dropdown

Build a user-friendly vehicle type selector:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_vehicle_type_options_for_ui(country_code):
    """Get vehicle types formatted for UI dropdown"""
    response = requests.get(
        "https://api.dcycle.io/v1/unknown-vehicles",
        headers=headers
    )

    vehicles = response.json()
    options = []

    for vehicle in vehicles:
        if vehicle['country'] == country_code:
            options.append({
                "label": vehicle['type'].capitalize(),
                "value": vehicle['id']
            })

    # Sort by label
    options.sort(key=lambda x: x['label'])
    return options

# Get options for dropdown
vehicle_options = get_vehicle_type_options_for_ui("ES")
print("Vehicle Type Options for Spain:")
for option in vehicle_options:
    print(f"  {option['label']}: {option['value']}")
```

### Validate Vehicle Type Input

Check if a provided vehicle type is valid:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def is_valid_vehicle_type(vehicle_type, country_code):
    """Check if provided vehicle type is valid for country"""
    response = requests.get(
        "https://api.dcycle.io/v1/unknown-vehicles",
        headers=headers
    )

    vehicles = response.json()
    valid_types = {
        f"{v['type']}_{v['country']}": v['id']
        for v in vehicles
    }

    key = f"{vehicle_type}_{country_code}"
    return key in valid_types, valid_types.get(key)

# Validate
is_valid, type_id = is_valid_vehicle_type("van", "ES")
if is_valid:
    print(f"Valid vehicle type with ID: {type_id}")
else:
    print("Invalid vehicle type")
```

### Cache Vehicle Type Data Locally

Cache vehicle type reference data to minimize API calls:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import json
from datetime import datetime, timedelta

class VehicleTypeCache:
    def __init__(self, cache_file="vehicle_types_cache.json", ttl_hours=24):
        self.cache_file = cache_file
        self.ttl = timedelta(hours=ttl_hours)

    def is_valid(self):
        """Check if cache is still valid"""
        try:
            with open(self.cache_file, 'r') as f:
                data = json.load(f)
                cached_at = datetime.fromisoformat(data['cached_at'])
                return datetime.now() - cached_at < self.ttl
        except:
            return False

    def get(self):
        """Get cached types or fetch fresh data"""
        if self.is_valid():
            with open(self.cache_file, 'r') as f:
                return json.load(f)['vehicles']

        # Fetch fresh data
        response = requests.get(
            "https://api.dcycle.io/v1/unknown-vehicles",
            headers=headers
        )
        vehicles = response.json()

        # Cache it
        with open(self.cache_file, 'w') as f:
            json.dump({
                'vehicles': vehicles,
                'cached_at': datetime.now().isoformat()
            }, f)

        return vehicles

# Use cache
cache = VehicleTypeCache()
vehicle_types = cache.get()
print(f"Using {len(vehicle_types)} cached vehicle types")
```

### Build a Vehicle Type Selector Wizard

Create an interactive selector for vehicle creation:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def select_vehicle_type_by_category(usage_type="freight"):
    """Select vehicle type based on usage category"""
    response = requests.get(
        "https://api.dcycle.io/v1/unknown-vehicles",
        headers=headers
    )

    vehicles = response.json()

    # Map usage types to vehicle categories
    category_map = {
        "freight": ["van", "truck", "lorry", "commercial"],
        "passenger": ["car", "sedan", "suv", "hatchback"],
        "specialty": ["ambulance", "taxi", "bus", "motorcycle"]
    }

    category = category_map.get(usage_type, [])
    matching = [
        v for v in vehicles
        if any(cat in v['type'].lower() for cat in category)
    ]

    return matching

# Get freight vehicles
freight_types = select_vehicle_type_by_category("freight")
print(f"Available freight vehicle types: {len(freight_types)}")
for vtype in freight_types:
    print(f"  - {vtype['type']}")
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Vehicle" icon="plus" href="/api-reference/vehicles/create">
    Create vehicles with specific vehicle types
  </Card>

  <Card title="List Vehicles" icon="list" href="/api-reference/vehicles/list">
    View vehicles and their type assignments
  </Card>

  <Card title="Vehicle Fuels" icon="droplet" href="/api-reference/vehicle-fuels/overview">
    Browse available fuel types
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Manage your vehicle fleet
  </Card>
</CardGroup>