> ## 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.
# Unknown Vehicles API
> Manage vehicle type classifications for unspecified or generic vehicles
# 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:
Your API key for authentication
**Format:** Your API key string
## Available Endpoints
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
```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"
}
```
## 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
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"detail": "Error description",
"code": "ERROR_CODE"
}
```
## Use Cases
### Build Vehicle Type Selection UI
Display available vehicle types in your application:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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")
```
## Related Documentation
Create vehicles with specific vehicle types
View vehicles and their type assignments
Browse available fuel types
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