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.

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.

Request

Headers

Authorization

string

required

Bearer token for authenticationFormat: Bearer {API_KEY} or Bearer {JWT_TOKEN}

Response

array

array[object]

Array of vehicle type objects

Show Vehicle Type Object

string

Unique identifier (UUID) for the vehicle type

type

string

Vehicle type name (e.g., “van”, “truck”, “car”, “suv”)

country

string

ISO 3166-1 two-letter country code for emission factors

created_at

datetime

Timestamp when the vehicle type was created

updated_at

datetime

Timestamp when the vehicle type was last updated

Example

curl -X GET "https://api.dcycle.io/v1/unknown-vehicles" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}"

Successful Response

[
  {
    "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

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active. Get a new one from Settings → API.

500 Internal Server Error

Cause: Server error retrieving vehicle type data

{
  "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:

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:

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:

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")

Build a user-friendly vehicle type selector:

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:

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:

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:

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']}")

Create Vehicle

Create vehicles with specific vehicle types

List Vehicles

View vehicles and their type assignments

Vehicle Fuels

Browse available fuel types

Vehicles API

Manage your vehicle fleet

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

List Unknown Vehicles

List Unknown Vehicles

Request

Headers

Response

Example

Successful Response

Common Errors

401 Unauthorized

500 Internal Server Error

Use Cases

Get All Vehicle Types for Vehicle Creation

Filter Vehicle Types by Country

Group Vehicle Types by Name

Validate Vehicle Type Input

Cache Vehicle Type Data Locally

Build a Vehicle Type Selector Wizard

Create Vehicle

List Vehicles

Vehicle Fuels

Vehicles API

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

​List Unknown Vehicles

​Request

​Headers

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​500 Internal Server Error

​Use Cases

​Get All Vehicle Types for Vehicle Creation

​Filter Vehicle Types by Country

​Group Vehicle Types by Name

​Create Vehicle Type Selection Dropdown

​Validate Vehicle Type Input

​Cache Vehicle Type Data Locally

​Build a Vehicle Type Selector Wizard

​Related Endpoints

Create Vehicle

List Vehicles

Vehicle Fuels

Vehicles API

List Unknown Vehicles

Request

Headers

Response

Example

Successful Response

Common Errors

401 Unauthorized

500 Internal Server Error

Use Cases

Get All Vehicle Types for Vehicle Creation

Filter Vehicle Types by Country

Group Vehicle Types by Name

Create Vehicle Type Selection Dropdown

Validate Vehicle Type Input

Cache Vehicle Type Data Locally

Build a Vehicle Type Selector Wizard

Related Endpoints