> ## 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 Vehicle Types
> Get a list of generic vehicle types available for unknown vehicles
# List Unknown Vehicle Types
Retrieve all unknown vehicle types available in the Dcycle system. Unknown vehicle types are generic vehicle categories used when you don't have specific make/model information from the known vehicles database.
Unknown vehicle types are **reference data** maintained by Dcycle. These are used when creating vehicles with `is_known: false` in bulk uploads.
## What are Unknown Vehicles?
When creating vehicles, you have two options:
1. **Known Vehicles** (`is_known: true`) - Specific make/model from Dcycle's database with detailed specifications
2. **Unknown Vehicles** (`is_known: false`) - Generic vehicle types with average emission factors
Unknown vehicles use generic emission factors based on vehicle type, fuel, and country, making them suitable for:
* Fleet vehicles without detailed specifications
* Third-party logistics providers
* Estimated emissions when exact vehicle data is unavailable
## Request
### Headers
Your API key for authentication
**Example:** `sk_live_1234567890abcdef`
Your organization UUID
**Example:** `ff4adcc7-8172-45fe-9cf1-e90a6de53aa9`
Your user UUID
**Example:** `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
No query parameters required.
## Response
Array of unknown vehicle type objects
Unique vehicle type identifier (UUID v4)
Vehicle type classification
**Valid types:**
* `passenger_car` - Standard passenger cars
* `light_commercial` - Light commercial vehicles (vans, small trucks)
* `rigid` - Rigid trucks
* `articulated` - Articulated trucks (semi-trailers)
* `motorcycle` - Motorcycles and scooters
* `bus` - Buses and coaches
ISO 3166-1 alpha-2 country code where emission factors apply
## Example
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET "https://api.dcycle.io/api/v1/unknown_vehicles" \
-H "Authorization: Bearer ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "x-user-id: ${DCYCLE_USER_ID}"
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
import os
api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")
user_id = os.getenv("DCYCLE_USER_ID")
headers = {
"Authorization": f"Bearer {api_key}",
"x-organization-id": org_id,
"x-user-id": user_id
}
response = requests.get(
"https://api.dcycle.io/api/v1/unknown_vehicles",
headers=headers
)
vehicle_types = response.json()
print(f"Found {len(vehicle_types)} unknown vehicle types:")
# Group by country
by_country = {}
for vtype in vehicle_types:
country = vtype['country']
if country not in by_country:
by_country[country] = []
by_country[country].append(vtype)
# Display by country
for country, types in by_country.items():
print(f"\n{country} - {len(types)} vehicle types:")
for vtype in types:
print(f" - {vtype['type']}")
```
```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const axios = require('axios');
const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;
const userId = process.env.DCYCLE_USER_ID;
const headers = {
'Authorization': `Bearer ${apiKey}`,
'x-organization-id': orgId,
'x-user-id': userId
};
axios.get('https://api.dcycle.io/api/v1/unknown_vehicles', { headers })
.then(response => {
const vehicleTypes = response.data;
console.log(`Found ${vehicleTypes.length} unknown vehicle types:`);
// Group by country
const byCountry = {};
vehicleTypes.forEach(vtype => {
if (!byCountry[vtype.country]) {
byCountry[vtype.country] = [];
}
byCountry[vtype.country].push(vtype);
});
// Display by country
Object.keys(byCountry).forEach(country => {
const types = byCountry[country];
console.log(`\n${country} - ${types.length} vehicle types:`);
types.forEach(vtype => {
console.log(` - ${vtype.type}`);
});
});
})
.catch(error => console.error(error));
```
### Successful Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "passenger_car",
"country": "ES"
},
{
"id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
"type": "light_commercial",
"country": "ES"
},
{
"id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
"type": "rigid",
"country": "ES"
},
{
"id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
"type": "articulated",
"country": "ES"
},
{
"id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
"type": "motorcycle",
"country": "ES"
},
{
"id": "f6g7h8i9-j0k1-2345-fghi-jk6789012345",
"type": "bus",
"country": "ES"
},
{
"id": "g7h8i9j0-k1l2-3456-ghij-kl7890123456",
"type": "passenger_car",
"country": "GLO"
},
{
"id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
"type": "light_commercial",
"country": "GLO"
}
]
```
## Common Errors
### 403 Forbidden
**Cause:** Organization ID doesn't match your API key or user doesn't belong to organization
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"detail": "Not authorized",
"code": "FORBIDDEN"
}
```
**Solution:** Verify that `x-organization-id` matches your API key's organization.
## Use Cases
### Build Vehicle Type Selector for Unknown Vehicles
Create a dropdown for selecting unknown vehicle types when bulk uploading:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_vehicle_type_selector(country="ES"):
"""Get unknown vehicle types for a specific country"""
response = requests.get(
"https://api.dcycle.io/api/v1/unknown_vehicles",
headers=headers
)
all_types = response.json()
# Filter by country
country_types = [
vtype for vtype in all_types
if vtype['country'] == country
]
# If no country-specific types, use global
if not country_types:
country_types = [
vtype for vtype in all_types
if vtype['country'] == 'GLO'
]
print(f"Vehicle types for {country}:")
for vtype in country_types:
print(f" {vtype['id']}: {vtype['type']}")
return country_types
# Usage
vehicle_types = get_vehicle_type_selector("ES")
```
### Validate Vehicle Type Before Bulk Upload
Ensure the vehicle type exists before creating unknown vehicles:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def validate_unknown_vehicle_type(vehicle_type, country):
"""Validate that an unknown vehicle type exists"""
response = requests.get(
"https://api.dcycle.io/api/v1/unknown_vehicles",
headers=headers
)
vehicle_types = response.json()
# Find matching type
for vtype in vehicle_types:
if vtype['type'] == vehicle_type and vtype['country'] == country:
return vtype['id']
# Try global if country-specific not found
for vtype in vehicle_types:
if vtype['type'] == vehicle_type and vtype['country'] == 'GLO':
return vtype['id']
raise ValueError(
f"Unknown vehicle type '{vehicle_type}' not found for country '{country}'"
)
# Usage
try:
unknown_vehicle_id = validate_unknown_vehicle_type("passenger_car", "ES")
print(f"✅ Valid vehicle type, ID: {unknown_vehicle_id}")
except ValueError as e:
print(f"❌ {e}")
```
### Map Vehicle Type to Fuels
Combine with vehicle fuels endpoint to show available fuels for each type:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_vehicle_type_with_fuels(country="ES"):
"""Get unknown vehicle types with their available fuels"""
# Get unknown vehicle types
response1 = requests.get(
"https://api.dcycle.io/api/v1/unknown_vehicles",
headers=headers
)
vehicle_types = response1.json()
# Get vehicle fuels
result = {}
for vtype in vehicle_types:
if vtype['country'] != country:
continue
# Get fuels for this vehicle type
response2 = requests.get(
"https://api.dcycle.io/api/v1/vehicle_fuels",
headers=headers,
params={
"vehicle_type": vtype['type'],
"country": country
}
)
fuels = response2.json()
result[vtype['type']] = {
'id': vtype['id'],
'fuels': [f['fuel'] for f in fuels]
}
return result
# Usage
vehicle_fuels_map = get_vehicle_type_with_fuels("ES")
print("Vehicle Types with Available Fuels:")
for vtype, data in vehicle_fuels_map.items():
print(f"\n{vtype}:")
print(f" Fuels: {', '.join(data['fuels'])}")
```
### Cache Unknown Vehicle Types
Since vehicle types rarely change, cache them:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from datetime import datetime, timedelta
class UnknownVehicleTypesCache:
def __init__(self, api_key, org_id, user_id):
self.headers = {
"Authorization": f"Bearer {api_key}",
"x-organization-id": org_id,
"x-user-id": user_id
}
self._cache = None
self._cache_time = None
self.cache_duration = timedelta(days=7)
def get_types(self):
"""Get vehicle types with caching"""
if (self._cache is None or
datetime.now() - self._cache_time > self.cache_duration):
self._refresh_cache()
return self._cache
def _refresh_cache(self):
"""Refresh the cache"""
response = requests.get(
"https://api.dcycle.io/api/v1/unknown_vehicles",
headers=self.headers
)
self._cache = response.json()
self._cache_time = datetime.now()
print(f"✅ Unknown vehicle types cache refreshed: {len(self._cache)} types")
def get_type_by_id(self, type_id):
"""Get a specific type by ID"""
types = self.get_types()
for vtype in types:
if vtype['id'] == type_id:
return vtype
return None
def get_types_by_country(self, country):
"""Get types for a specific country"""
types = self.get_types()
country_types = [
vtype for vtype in types
if vtype['country'] == country
]
# Fallback to global if no country-specific types
if not country_types:
country_types = [
vtype for vtype in types
if vtype['country'] == 'GLO'
]
return country_types
def get_type_id(self, vehicle_type, country):
"""Get type ID by type name and country"""
types = self.get_types()
# Try country-specific first
for vtype in types:
if vtype['type'] == vehicle_type and vtype['country'] == country:
return vtype['id']
# Fallback to global
for vtype in types:
if vtype['type'] == vehicle_type and vtype['country'] == 'GLO':
return vtype['id']
return None
# Usage
cache = UnknownVehicleTypesCache(
api_key=os.getenv("DCYCLE_API_KEY"),
org_id=os.getenv("DCYCLE_ORG_ID"),
user_id=os.getenv("DCYCLE_USER_ID")
)
# Get passenger car ID for Spain
passenger_car_id = cache.get_type_id("passenger_car", "ES")
print(f"Passenger car ID for ES: {passenger_car_id}")
```
## Vehicle Type Details
### Passenger Car (`passenger_car`)
* **Description:** Standard passenger vehicles (sedans, hatchbacks, SUVs)
* **Common Use:** Company cars, employee vehicles, rental cars
* **Typical Fuels:** Gasoline, Diesel, Electric, Hybrid, CNG
* **Emission Factors:** Based on average passenger car in region
### Light Commercial (`light_commercial`)
* **Description:** Light commercial vehicles, vans, small trucks (\< 3.5 tonnes)
* **Common Use:** Delivery vans, service vehicles, small cargo transport
* **Typical Fuels:** Diesel, Gasoline, Electric, CNG
* **Emission Factors:** Based on light-duty commercial vehicle averages
### Rigid (`rigid`)
* **Description:** Rigid trucks (single-unit trucks > 3.5 tonnes)
* **Common Use:** Local delivery trucks, waste collection, construction
* **Typical Fuels:** Diesel, CNG, LNG
* **Emission Factors:** Based on truck weight class and load factor
### Articulated (`articulated`)
* **Description:** Articulated trucks (tractor-trailer combinations, semi-trailers)
* **Common Use:** Long-haul freight, interstate transport
* **Typical Fuels:** Diesel, LNG
* **Emission Factors:** Based on heavy-duty long-haul averages
### Motorcycle (`motorcycle`)
* **Description:** Motorcycles, scooters, mopeds
* **Common Use:** Courier services, urban delivery, personal transport
* **Typical Fuels:** Gasoline, Electric
* **Emission Factors:** Based on engine size and fuel type
### Bus (`bus`)
* **Description:** Buses and coaches for passenger transport
* **Common Use:** Employee shuttles, tour buses, public transport
* **Typical Fuels:** Diesel, CNG, Electric, Hybrid
* **Emission Factors:** Based on bus type and occupancy
## Country-Specific vs Global
### Country-Specific Types (e.g., ES, FR, DE)
Country-specific unknown vehicle types use emission factors based on:
* National vehicle fleet composition
* Regional fuel standards
* Country-specific driving conditions
* Local regulations
**Available for:** Spain (`ES`), and expanding to other countries
### Global Types (GLO)
Global types use international average emission factors:
* Based on IPCC guidelines
* Suitable for multi-country operations
* Used when country-specific data unavailable
* More conservative estimates
Always prefer country-specific types when available for more accurate emissions calculations. Global types provide reasonable estimates for countries without specific data.
## Best Practices
### 1. Cache Reference Data
Vehicle types change very rarely, cache for extended periods:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Good - Cache for 7 days
cache = UnknownVehicleTypesCache()
types = cache.get_types()
# Bad - Fetch every time
types = requests.get("https://api.dcycle.io/api/v1/unknown_vehicles")
```
### 2. Use Country-Specific Types
Always use country-specific types when available:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Good - Use country-specific
type_id = cache.get_type_id("passenger_car", "ES")
# Acceptable - Fallback to global if country-specific unavailable
if not type_id:
type_id = cache.get_type_id("passenger_car", "GLO")
```
### 3. Store Type IDs in Configuration
For common vehicle types, store their IDs:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# config.py
COMMON_VEHICLE_TYPES_ES = {
'passenger_car': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
'light_commercial': 'b2c3d4e5-f6g7-8901-bcde-fg2345678901',
'rigid': 'c3d4e5f6-g7h8-9012-cdef-gh3456789012'
}
# Usage - No API call needed
vehicle_data = {
"unknown_vehicle_id": COMMON_VEHICLE_TYPES_ES['passenger_car'],
# ... other fields
}
```
### 4. Validate Before Bulk Upload
Always validate vehicle type exists before CSV upload:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def prepare_vehicle_csv(vehicles_data, country):
# Get valid types
valid_types = cache.get_types_by_country(country)
valid_type_names = {vt['type'] for vt in valid_types}
# Validate each vehicle
for vehicle in vehicles_data:
if vehicle['type'] not in valid_type_names:
raise ValueError(
f"Invalid vehicle type '{vehicle['type']}' for country '{country}'"
)
# Proceed with CSV creation
return create_csv(vehicles_data)
```
## Related Endpoints
Upload vehicles using unknown vehicle types
Get available fuels for vehicle types
View your vehicle fleet
Learn about API authentication