Unknown Vehicles API

The Unknown Vehicles API provides a catalog of vehicle type classifications for vehicles that don’t fit standard categories or when the specific make/model is not available. These types are used when creating vehicles in your fleet.

Reference Data: This API provides classification types for vehicles. Use the vehicle type IDs returned here when creating vehicles with the unknown_vehicle_id parameter.

Key Features

Vehicle Type Catalog: Browse all available vehicle type classifications
Country Support: Get vehicle types specific to different countries
Fleet Categorization: Classify vehicles without specific model information
Generic Categories: Support for freight, passenger, vans, trucks, and specialty vehicles
Reference Data: Use IDs from this API when creating vehicles

Authentication

All endpoints require authentication using an API key included in the x-api-key header.

Headers

All requests should include:

string

required

Your API key for authenticationFormat: Your API key string

Available Endpoints

List Unknown Vehicles

Retrieve all available vehicle type classifications

Vehicle Type Categories

Unknown vehicles are typically categorized into:

Category	Description	Examples
Passenger Car	Standard passenger vehicles	Car, Sedan, Hatchback, SUV
Light Commercial	Small commercial vehicles	Van, Pickup, Small Truck
Heavy Commercial	Large commercial vehicles	Truck, Semi-trailer, Tanker
Specialty	Specialized vehicles	Ambulance, Taxi, Bus
Motorcycle	Two-wheel vehicles	Motorcycle, Scooter, Moped
Generic	Unclassified or generic vehicle	Vehicle, Transport, Mobile

Unknown Vehicle Object Structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "van",
  "country": "ES",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Workflow

Using Unknown Vehicle Types with Vehicles

List available types using GET /v1/unknown-vehicles
Select a vehicle type based on:
- Vehicle category (van, truck, car, etc.)
- Country (emission factors vary by region)
Use the type ID when creating or updating vehicles with unknown_vehicle_id

Common Usage Patterns

# 1. Get all available vehicle types
vehicle_types = requests.get(
    "https://api.dcycle.io/v1/unknown-vehicles",
    headers=headers
).json()

# 2. Find van type for Spain
van_es = next(
    t for t in vehicle_types
    if t["type"] == "van" and t["country"] == "ES"
)

# 3. Use the type ID when creating a vehicle
vehicle = {
    "name": "Delivery Van",
    "type": "freight",
    "ownership": "owned",
    "license_plate": "XYZ-5678",
    "country": "ES",
    "unknown_vehicle_id": van_es["id"],  # Reference from unknown vehicles API
    "vehicle_fuel_id": "660e8400-e29b-41d4-a716-446655440000"
}

Error Handling

Common HTTP Status Codes

Status	Meaning	Solution
200	Success	-
401	Unauthorized	Verify API key or JWT token
500	Server Error	Contact support if persists

Error Response Format

{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

Use Cases

Build Vehicle Type Selection UI

Display available vehicle types in your application:

def get_vehicle_types_for_country(country_code):
    """Get all vehicle types available 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_for_country("ES")
for vehicle in spain_vehicles:
    print(f"{vehicle['type']}: {vehicle['id']}")

Map Vehicle Types to Categories

Organize vehicle types for display:

def get_vehicle_types_by_category():
    """Group all vehicle types by category"""
    response = requests.get(
        "https://api.dcycle.io/v1/unknown-vehicles",
        headers=headers
    )

    vehicles = response.json()
    categories = {
        "passenger": [],
        "commercial": [],
        "specialty": []
    }

    for vehicle in vehicles:
        vehicle_type = vehicle["type"].lower()
        if any(x in vehicle_type for x in ["car", "sedan", "suv", "hatchback"]):
            categories["passenger"].append(vehicle)
        elif any(x in vehicle_type for x in ["van", "truck", "commercial"]):
            categories["commercial"].append(vehicle)
        else:
            categories["specialty"].append(vehicle)

    return categories

# Get categorized types
categorized = get_vehicle_types_by_category()
for category, vehicles in categorized.items():
    print(f"{category}: {len(vehicles)} types")

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

Rate Limiting

API requests are subject to rate limiting. Include rate limit information from response headers:

X-RateLimit-Limit: Maximum requests per minute
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp when limit resets

Bulk Delete Vehicle Consumptions by Filters (Organization)List Unknown Vehicles

​Unknown Vehicles API

​Key Features

​Authentication

​Headers

​Available Endpoints

List Unknown Vehicles

​Vehicle Type Categories

​Unknown Vehicle Object Structure

​Workflow

​Using Unknown Vehicle Types with Vehicles

​Common Usage Patterns

​Error Handling

​Common HTTP Status Codes

​Error Response Format

​Use Cases

​Build Vehicle Type Selection UI

​Map Vehicle Types to Categories

​Related Documentation

Create Vehicle

List Vehicles

Vehicle Fuels

Vehicles API

​Rate Limiting

Unknown Vehicles API

Key Features

Authentication

Headers

Available Endpoints

Vehicle Type Categories

Unknown Vehicle Object Structure

Workflow

Using Unknown Vehicle Types with Vehicles

Common Usage Patterns

Error Handling

Common HTTP Status Codes

Error Response Format

Use Cases

Build Vehicle Type Selection UI

Map Vehicle Types to Categories

Related Documentation

Rate Limiting