​

Vehicles API

​

Key Features

• Fleet Management: Create and manage vehicles in your organization
• Flexible Vehicle Configuration: Support for both known vehicles (with fuel types) and unknown vehicle types
• CO2e Calculation: Automatic emissions calculation based on vehicle characteristics
• Regional Support: ISO country codes for region-specific emission factors
• Market Segmentation: Classify vehicles by market segment for accurate categorization
• Pagination Support: Efficiently retrieve large lists of vehicles

​

Authentication

• API Key: Include in Authorization header as Bearer {API_KEY}
• JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​

Headers

​

Available Endpoints

​

Vehicle Attributes

​

Core Vehicle Information

• name (string, optional): Custom name or alias for the vehicle (e.g., “Company Fleet Car #1”)
• type (string, required): Type of vehicle usage - passenger or freight
• ownership (string, required): Ownership type - owned or rented
• license_plate (string, required): Vehicle registration/license plate number
• country (string, required): ISO 3166-1 country code (2-3 characters)

​

Vehicle Classification

• unknown_vehicle_id (UUID, required): UUID of the unknown vehicle type for categorization
• vehicle_fuel_id (UUID, optional): UUID of the vehicle fuel type (petrol, diesel, electric, hybrid, etc.)
• registration_year (integer, optional): Year of vehicle registration (YYYY format)
• market_segment (string, optional): Vehicle market segment classification
• size (string, optional): Vehicle size category (small, medium, large)

​

Emission Data

• custom_emission_factor_id (UUID, optional): UUID of a custom emission factor for organizations with custom emission data
• co2e (float, read-only): Calculated CO2 equivalent emissions in kg CO2e

​

Workflow

​

Creating a Fleet Vehicle

1. Retrieve available options (if needed):
   • Get unknown vehicle types from /vehicles/unknown endpoint
   • Get fuel types from /vehicles/fuels endpoint
   • Get market segments from /vehicles/market-segments endpoint
2. Create the vehicle with:
   • Required fields: type, ownership, license_plate, country, unknown_vehicle_id
   • Either vehicle_fuel_id or custom_emission_factor_id for emissions calculation
3. Track emissions through the co2e field in responses

​

Filtering and Pagination

• Filter by status (active, archived, error)
• Filter by ownership type (owned, rented)
• Filter by fuel type or unknown vehicle type
• Search by vehicle name or license plate
• Sort results (by name, license plate, creation date)
• Include child organizations in results

​

Response Format

​

Vehicle Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Company Fleet Car #1",
  "type": "passenger",
  "ownership": "owned",
  "license_plate": "ABC-1234",
  "country": "ES",
  "status": "active",
  "co2e": 245.5,
  "vehicle_fuel_id": "660e8400-e29b-41d4-a716-446655440000",
  "unknown_vehicle_type": null,
  "registration_year": 2022,
  "market_segment": "upper_medium",
  "size": "medium",
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30:00Z"
}

​

Pagination Response

{
  "items": [
    { "vehicle object" },
    { "vehicle object" }
  ],
  "total": 150,
  "page": 1,
  "size": 50,
  "pages": 3
}

​

Error Handling

​

Common HTTP Status Codes

​

Error Response Format

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

​

Use Cases

​

Track Corporate Fleet Emissions

# Get all active vehicles
vehicles = requests.get(
    "https://api.dcycle.io/v1/vehicles",
    headers={
        "Authorization": f"Bearer {api_key}",
        "x-organization-id": org_id
    },
    params={"status": ["active"]}
)

total_co2e = sum(v["co2e"] for v in vehicles.json()["items"])
print(f"Fleet total: {total_co2e} kg CO2e")

​

Compare Vehicle Options

# Create vehicles with different fuel types
vehicles_to_test = [
    {"name": "Diesel Van", "vehicle_fuel_id": diesel_uuid},
    {"name": "Electric Van", "vehicle_fuel_id": electric_uuid},
    {"name": "Hybrid Van", "vehicle_fuel_id": hybrid_uuid}
]

for vehicle in vehicles_to_test:
    response = requests.post(
        "https://api.dcycle.io/v1/vehicles",
        headers=headers,
        json=vehicle
    )
    data = response.json()
    print(f"{data['name']}: {data['co2e']} kg CO2e")

​

Related Documentation

​

Rate Limiting

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