Skip to main content

​
Vehicle Fuels API

The Vehicle Fuels API allows you to retrieve and manage fuel types available for vehicles in your organization. Each fuel type includes associated emission factors and units of measurement for accurate CO2e calculations.
Reference Data: This API provides reference data for fuel types used when creating or updating vehicles. Fuel types define how emissions are calculated based on vehicle usage.

​
Key Features

  • Fuel Type Catalog: Browse all available fuel types for your vehicles
  • Emission Factors: View standardized emission factors per fuel type
  • Unit Management: Access fuel units and conversion factors
  • Country-Specific: Get fuel data specific to different countries
  • Reference Data: Use IDs from this API when creating vehicles

​
Authentication

All endpoints require authentication using either:
  • API Key: Include in Authorization header as Bearer {API_KEY}
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests should include:
​
Authorization
string
required
Bearer token for authenticationFormat: Bearer {API_KEY} or Bearer {JWT_TOKEN}

​
Available Endpoints

List Vehicle Fuels

Retrieve all available fuel types with emission factors and units

​
Fuel Types

Common fuel types include:
Fuel TypeDescriptionEmission Factor (kg CO2e/unit)
PetrolGasoline/benzine fuel~2.31 per liter
DieselDiesel fuel~2.68 per liter
ElectricElectric battery powered~0.0 per kWh (upstream)
HybridPetrol-electric hybrid~1.5 per liter
LPGLiquified petroleum gas~1.54 per kg
Natural GasCompressed natural gas~2.04 per kg
HydrogenHydrogen fuel cell~0.0 per kg (production dependent)

​
Fuel Units

Fuel can be measured in various units:
UnitTypeDescription
literVolumeStandard fuel measurement for liquid fuels
kgMassUsed for gaseous and solid fuels
kWhEnergyUsed for electric vehicles
gallonVolumeUS/Imperial fuel measurement
m³VolumeCubic meters for gaseous fuels

​
Fuel Object Structure

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "fuel": "diesel",
  "country": "ES",
  "fuel_units": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "liters",
      "type": "volume"
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440001",
      "name": "gallons",
      "type": "volume"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
Workflow

​
Using Fuel Types with Vehicles

  1. List available fuels using GET /v1/vehicle-fuels
  2. Select a fuel type for your vehicle based on:
    • Fuel type (petrol, diesel, electric, etc.)
    • Country (emission factors vary by region)
  3. Use the fuel ID when creating or updating vehicles with vehicle_fuel_id

​
Common Usage Patterns

# 1. Get all available fuels
fuels = requests.get(
    "https://api.dcycle.io/v1/vehicle-fuels",
    headers=headers
).json()

# 2. Find diesel fuel for Spain
diesel_es = next(
    f for f in fuels
    if f["fuel"] == "diesel" and f["country"] == "ES"
)

# 3. Use the fuel ID when creating a vehicle
vehicle = {
    "name": "Diesel Van",
    "type": "freight",
    "ownership": "owned",
    "license_plate": "XYZ-5678",
    "country": "ES",
    "unknown_vehicle_id": "550e8400-e29b-41d4-a716-446655440001",
    "vehicle_fuel_id": diesel_es["id"]  # Reference from fuels API
}

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success-
401UnauthorizedVerify API key or JWT token
500Server ErrorContact support if persists

​
Error Response Format

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

​
Use Cases

​
Build Fuel Selection UI

Display available fuels in your application: 
def get_fuels_for_country(country_code):
    """Get all fuels available for a specific country"""
    response = requests.get(
        "https://api.dcycle.io/v1/vehicle-fuels",
        headers=headers
    )

    fuels = response.json()
    country_fuels = [
        f for f in fuels
        if f["country"] == country_code
    ]

    return country_fuels

# Get fuels for Spain
spain_fuels = get_fuels_for_country("ES")
for fuel in spain_fuels:
    print(f"{fuel['fuel']}: {fuel['id']}")

​
Compare Emissions by Fuel Type

Analyze how fuel type affects emissions: 
def compare_fuel_emissions(vehicle_data):
    """Compare CO2e for same vehicle with different fuels"""
    fuels = requests.get(
        "https://api.dcycle.io/v1/vehicle-fuels",
        headers=headers
    ).json()

    results = {}
    for fuel in fuels:
        # Create vehicle with this fuel
        vehicle_payload = {
            **vehicle_data,
            "vehicle_fuel_id": fuel["id"]
        }

        response = requests.post(
            "https://api.dcycle.io/v1/vehicles",
            headers=headers,
            json=vehicle_payload
        )

        if response.status_code == 201:
            vehicle = response.json()
            results[fuel["fuel"]] = {
                "co2e": vehicle["co2e"],
                "fuel_id": fuel["id"]
            }

    return results

Create Vehicle

Create vehicles with specific fuel types

List Vehicles

View vehicles and their fuel assignments

Unknown Vehicles

Browse vehicle type classifications

Vehicles API

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