Skip to main content
GET
/
api
/
v1
/
vehicles
List Vehicles
const options = {
  method: 'GET',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'x-user-id': '<x-user-id>'
  }
};

fetch('https://api.dcycle.io/api/v1/vehicles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "page": 123,
  "size": 123,
  "total": 123,
  "total_archived": 123,
  "items": [
    {}
  ]
}

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 Vehicles

Retrieve all vehicles registered in your organization’s fleet with pagination support and flexible filtering options.
This endpoint returns both known vehicles (from our database with specific make/model) and unknown vehicles (custom vehicles defined by the user).

​
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

​
Query Parameters

​
page
integer
default:"1"
Page number for paginationExample: 1
​
size
integer
default:"50"
Number of items per page (max: 100)Example: 50
​
filter_by
string
Advanced filtering criteria (format: field:value)Example: "country:ES", "type:passenger", "ownership:owned"
​
sort_by
string
Sort criteria (format: field:asc or field:desc)Example: "name:asc", "created_at:desc", "license_plate:asc"
​
start_date
integer
Filter by creation date start (Unix timestamp)Example: 1704067200 (January 1, 2024)
​
end_date
integer
Filter by creation date end (Unix timestamp)Example: 1735689600 (January 1, 2025)

​
Response

​
page
integer
Current page number
​
size
integer
Number of items per page
​
total
integer
Total count of active vehicles
​
total_archived
integer
Total count of archived vehicles
​
items
array
Array of vehicle objects

​
Vehicle Object Fields:

  • id (string, UUID) - Unique vehicle identifier
  • name (string, optional) - Vehicle name or description
  • license_plate (string, optional) - Vehicle license plate number
  • type (string) - Vehicle usage type: "passenger" or "freight"
  • ownership (string) - Vehicle ownership: "owned" or "rented"
  • country (string) - ISO 3166-1 alpha-2 country code
  • is_known (boolean) - Whether vehicle is from known database or custom
  • known_vehicle_id (string, UUID, optional) - ID if vehicle from database
  • unknown_vehicle_id (string, UUID, optional) - ID if custom vehicle
  • vehicle_fuel_id (string, UUID, optional) - Associated fuel type ID
  • vehicle_fuel (string, optional) - Fuel type name (e.g., “Diesel”, “Electric”)
  • registration_year (integer, optional) - Year vehicle was first registered
  • market_segment (string, optional) - Vehicle market segment
  • size (string, optional) - Vehicle size classification
  • co2e (float) - Total CO2 equivalent emissions in kg
  • consumptions (integer, optional) - Number of fuel consumption records
  • status (string) - "active", "archived", or "error"
  • error_messages (array of strings, optional) - Error messages if status is error
  • created_at (datetime) - Creation timestamp
  • known_vehicle (object, optional) - Details if known vehicle
    • id (string) - Known vehicle database ID
    • brand (string) - Vehicle manufacturer
    • model (string) - Vehicle model
    • country (string) - Country code
    • vehicle_motor_type (string) - Motor type
    • gearbox_type (string) - Transmission type
    • cylinder_capacity (integer) - Engine size in cc
    • vehicle_power (integer) - Engine power in kW
  • unknown_vehicle (object, optional) - Details if custom vehicle
    • id (string) - Custom vehicle ID
    • type (string) - Vehicle type
    • country (string) - Country code
  • custom_emission_factor_id (string, UUID, optional) - Custom emission factor if specified

​
Example

curl -X GET "https://api.dcycle.io/api/v1/vehicles?page=1&size=50&type=passenger" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

​
Successful Response

{
  "page": 1,
  "size": 50,
  "total": 45,
  "total_archived": 8,
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Company Van #1",
      "license_plate": "1234-ABC",
      "type": "freight",
      "ownership": "owned",
      "country": "ES",
      "is_known": true,
      "known_vehicle_id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
      "unknown_vehicle_id": null,
      "vehicle_fuel_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
      "vehicle_fuel": "Diesel",
      "registration_year": 2020,
      "market_segment": "lower_medium",
      "size": "medium",
      "co2e": 4532.75,
      "consumptions": 24,
      "status": "active",
      "error_messages": null,
      "created_at": "2024-01-15T10:30:00Z",
      "known_vehicle": {
        "id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
        "brand": "Ford",
        "model": "Transit Custom",
        "country": "ES",
        "vehicle_motor_type": "Diesel",
        "gearbox_type": "Manual",
        "cylinder_capacity": 1998,
        "vehicle_power": 96
      },
      "unknown_vehicle": null,
      "custom_emission_factor_id": null
    },
    {
      "id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
      "name": "CEO Car",
      "license_plate": "9876-XYZ",
      "type": "passenger",
      "ownership": "owned",
      "country": "ES",
      "is_known": true,
      "known_vehicle_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
      "unknown_vehicle_id": null,
      "vehicle_fuel_id": "f6g7h8i9-j0k1-2345-fghi-jk6789012345",
      "vehicle_fuel": "Electric",
      "registration_year": 2023,
      "market_segment": "executive",
      "size": "large_car",
      "co2e": 856.20,
      "consumptions": 12,
      "status": "active",
      "error_messages": null,
      "created_at": "2023-08-22T14:15:00Z",
      "known_vehicle": {
        "id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
        "brand": "Tesla",
        "model": "Model S",
        "country": "ES",
        "vehicle_motor_type": "Electric",
        "gearbox_type": "Automatic",
        "cylinder_capacity": 0,
        "vehicle_power": 493
      },
      "unknown_vehicle": null,
      "custom_emission_factor_id": null
    },
    {
      "id": "g7h8i9j0-k1l2-3456-ghij-kl7890123456",
      "name": "Custom Delivery Truck",
      "license_plate": "5555-DEF",
      "type": "freight",
      "ownership": "rented",
      "country": "ES",
      "is_known": false,
      "known_vehicle_id": null,
      "unknown_vehicle_id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
      "vehicle_fuel_id": "i9j0k1l2-m3n4-5678-ijkl-mn9012345678",
      "vehicle_fuel": "Diesel",
      "registration_year": 2019,
      "market_segment": null,
      "size": null,
      "co2e": 8920.50,
      "consumptions": 36,
      "status": "active",
      "error_messages": null,
      "created_at": "2024-03-10T09:00:00Z",
      "known_vehicle": null,
      "unknown_vehicle": {
        "id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
        "type": "freight",
        "country": "ES"
      },
      "custom_emission_factor_id": null
    }
  ]
}

​
Common Errors

​
400 Bad Request

Cause: Invalid query parameters or date format 
{
  "detail": "Invalid date format",
  "code": "VALIDATION_ERROR"
}
Solution: Verify that dates are Unix timestamps (integers) and pagination parameters are positive integers.

​
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

​
Fleet Dashboard

Display your complete fleet with emissions breakdown: 
def get_fleet_dashboard():
    """Get vehicles for dashboard display"""
    response = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={"page": 1, "size": 100, "sort_by": "co2e:desc"}
    )

    vehicles = response.json()

    # Calculate totals
    total_emissions = sum(v['co2e'] for v in vehicles['items'])
    passenger_count = sum(1 for v in vehicles['items'] if v['type'] == 'passenger')
    freight_count = sum(1 for v in vehicles['items'] if v['type'] == 'freight')

    return {
        'vehicles': vehicles['items'],
        'total_active': vehicles['total'],
        'total_archived': vehicles['total_archived'],
        'total_emissions': total_emissions,
        'passenger_vehicles': passenger_count,
        'freight_vehicles': freight_count
    }

​
Filter by Vehicle Type

Get all passenger or freight vehicles: 
def get_vehicles_by_type(vehicle_type):
    """Get vehicles filtered by type (passenger or freight)"""
    response = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={
            "filter_by": f"type:{vehicle_type}",
            "page": 1,
            "size": 100
        }
    )

    vehicles = response.json()

    print(f"{vehicle_type.capitalize()} vehicles: {vehicles['total']}")
    for vehicle in vehicles['items']:
        name = vehicle.get('name', vehicle.get('license_plate', 'Unnamed'))
        fuel = vehicle.get('vehicle_fuel', 'Unknown fuel')
        print(f"  - {name} ({fuel}): {vehicle['co2e']:.2f} kg CO2e")

    return vehicles

# Example: Get all freight vehicles
freight_vehicles = get_vehicles_by_type("freight")

​
Filter by Ownership

Get owned vs rented vehicles: 
def compare_owned_vs_rented():
    """Compare emissions from owned vs rented vehicles"""
    # Get owned vehicles
    owned = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={"filter_by": "ownership:owned", "size": 100}
    ).json()

    # Get rented vehicles
    rented = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={"filter_by": "ownership:rented", "size": 100}
    ).json()

    owned_emissions = sum(v['co2e'] for v in owned['items'])
    rented_emissions = sum(v['co2e'] for v in rented['items'])

    print(f"Owned vehicles: {len(owned['items'])} ({owned_emissions:.2f} kg CO2e)")
    print(f"Rented vehicles: {len(rented['items'])} ({rented_emissions:.2f} kg CO2e)")

    return {
        'owned': {'count': len(owned['items']), 'emissions': owned_emissions},
        'rented': {'count': len(rented['items']), 'emissions': rented_emissions}
    }

​
Date Range Query

Get vehicles added within a specific time period: 
from datetime import datetime, timedelta

def get_recently_added_vehicles(days=30):
    """Get vehicles added in the last N days"""
    end_date = int(datetime.now().timestamp())
    start_date = int((datetime.now() - timedelta(days=days)).timestamp())

    response = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={
            "start_date": start_date,
            "end_date": end_date,
            "sort_by": "created_at:desc"
        }
    )

    vehicles = response.json()

    print(f"Vehicles added in last {days} days: {len(vehicles['items'])}")
    return vehicles

# Get vehicles from last 30 days
recent = get_recently_added_vehicles(30)

​
Pagination

When you have many vehicles, use pagination to retrieve all results: 
def get_all_vehicles():
    """Fetch all vehicles with pagination"""
    all_vehicles = []
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/api/v1/vehicles",
            headers=headers,
            params={"page": page, "size": 100}
        )

        data = response.json()
        all_vehicles.extend(data['items'])

        # Check if we've retrieved all items
        if len(all_vehicles) >= data['total']:
            break

        page += 1

    return all_vehicles

# Get all vehicles at once
all_vehicles = get_all_vehicles()
print(f"Total vehicles retrieved: {len(all_vehicles)}")

​
Special Notes

​
Known vs Unknown Vehicles

Dcycle maintains a database of known vehicles with specific make, model, and technical specifications. You can:
  • Use known vehicles: Select from database with accurate emission factors based on manufacturer data
  • Create unknown vehicles: Define custom vehicles when your specific model isn’t in our database
When a vehicle has is_known: true, the known_vehicle object contains detailed specifications. When is_known: false, the unknown_vehicle object contains basic type information.

​
Vehicle Types

Vehicles are classified by usage:
  • passenger: Personal vehicles, company cars, executive vehicles
  • freight: Delivery vans, trucks, commercial vehicles
This classification affects emission calculations and reporting.

​
Ownership Status

Track vehicle ownership for better fleet management:
  • owned: Vehicles owned by your organization
  • rented: Leased or rented vehicles
This helps distinguish between CAPEX and OPEX emissions in reporting.

​
Market Segments

For passenger vehicles, market segments help classify vehicle size and emissions:
  • mini - City cars (e.g., Smart ForTwo)
  • supermini - Small cars (e.g., Ford Fiesta)
  • lower_medium - Compact cars (e.g., VW Golf)
  • upper_medium - Mid-size cars (e.g., BMW 3 Series)
  • executive - Large cars (e.g., BMW 5 Series)
  • luxury - Premium cars (e.g., Mercedes S-Class)
  • sports - Sports cars
  • dual_purpose_4x4 - SUVs and 4x4 vehicles
  • mpv - Multi-purpose vehicles (minivans)

​
CO2e Field

The co2e field represents the total carbon footprint of the vehicle calculated from all fuel consumption records. A value of 0.0 means either:
  • No consumption records have been registered yet
  • All consumptions have zero emissions
  • Calculations are pending

​
Vehicle Status

Vehicles can have three statuses:
  • active: Vehicle is currently in use
  • archived: Vehicle removed from fleet but data retained for historical reporting
  • error: Vehicle has validation or processing errors (check error_messages field)

Bulk Upload Vehicles

Upload multiple vehicles via CSV

List Facilities

View your facilities

Create Invoice

Add fuel consumption data

Authentication

Learn about API authentication