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:

Known Vehicles (is_known: true) - Specific make/model from Dcycle’s database with detailed specifications
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

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

x-user-id

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

No query parameters required.

Response

[]

array

Array of unknown vehicle type objects

string

Unique vehicle type identifier (UUID v4)

type

string

Vehicle type classificationValid 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

country

string

ISO 3166-1 alpha-2 country code where emission factors apply

Example

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

Successful Response

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

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

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:

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:

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:

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:

# 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:

# 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:

# 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:

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)

Bulk Upload Vehicles

Upload vehicles using unknown vehicle types

List Vehicle Fuels

Get available fuels for vehicle types

List Vehicles

View your vehicle fleet

Authentication

Learn about API authentication

Introduction

Logistics

Facilities

Vehicles

Invoices

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

​List Unknown Vehicle Types

​What are Unknown Vehicles?

​Request

​Headers

​Response

​Example

​Successful Response

​Common Errors

​403 Forbidden

​Use Cases

​Build Vehicle Type Selector for Unknown Vehicles

​Validate Vehicle Type Before Bulk Upload

​Map Vehicle Type to Fuels

​Cache Unknown Vehicle Types

​Vehicle Type Details

​Passenger Car (passenger_car)

​Light Commercial (light_commercial)

​Rigid (rigid)

​Articulated (articulated)

​Motorcycle (motorcycle)

​Bus (bus)

​Country-Specific vs Global

​Country-Specific Types (e.g., ES, FR, DE)

​Global Types (GLO)

​Best Practices

​1. Cache Reference Data

​2. Use Country-Specific Types

​3. Store Type IDs in Configuration

​4. Validate Before Bulk Upload

​Related Endpoints

Bulk Upload Vehicles

List Vehicle Fuels

List Vehicles

Authentication

List Unknown Vehicle Types

What are Unknown Vehicles?

Request

Headers

Response

Example

Successful Response

Common Errors

403 Forbidden

Use Cases

Build Vehicle Type Selector for Unknown Vehicles

Validate Vehicle Type Before Bulk Upload

Map Vehicle Type to Fuels

Cache Unknown Vehicle Types

Vehicle Type Details

Passenger Car (`passenger_car`)

Light Commercial (`light_commercial`)

Rigid (`rigid`)

Articulated (`articulated`)

Motorcycle (`motorcycle`)

Bus (`bus`)

Country-Specific vs Global

Country-Specific Types (e.g., ES, FR, DE)

Global Types (GLO)

Best Practices

1. Cache Reference Data

2. Use Country-Specific Types

3. Store Type IDs in Configuration

4. Validate Before Bulk Upload

Related Endpoints