Skip to main content

​
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 either:
  • API Key: Include in Authorization header as Bearer {API_KEY}
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests should include:
​
Authorization
string
required
Bearer token for authenticationFormat: Bearer {API_KEY} or Bearer {JWT_TOKEN}

​
Available Endpoints

List Unknown Vehicles

Retrieve all available vehicle type classifications

​
Vehicle Type Categories

Unknown vehicles are typically categorized into:
CategoryDescriptionExamples
Passenger CarStandard passenger vehiclesCar, Sedan, Hatchback, SUV
Light CommercialSmall commercial vehiclesVan, Pickup, Small Truck
Heavy CommercialLarge commercial vehiclesTruck, Semi-trailer, Tanker
SpecialtySpecialized vehiclesAmbulance, Taxi, Bus
MotorcycleTwo-wheel vehiclesMotorcycle, Scooter, Moped
GenericUnclassified or generic vehicleVehicle, 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

  1. List available types using GET /v1/unknown-vehicles
  2. Select a vehicle type based on:
    • Vehicle category (van, truck, car, etc.)
    • Country (emission factors vary by region)
  3. 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

StatusMeaningSolution
200Success-
401UnauthorizedVerify API key or JWT token
500Server ErrorContact 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