List Vehicle Fuels

Retrieve all available fuel types with emission factors and units

GET /v1/vehicle-fuels

List Vehicle Fuels

JavaScript

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://api.dcycle.io/v1/vehicle-fuels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "array": {
    "id": "<string>",
    "fuel": "<string>",
    "country": "<string>",
    "fuel_units": {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    },
    "created_at": {},
    "updated_at": {}
  }
}

← Vehicle Fuels API

Retrieve all available fuel types in the system. Each fuel type includes emission factors and available units of measurement for accurate CO2e calculations.

Reference Data: This endpoint returns standardized fuel types used across the platform. Use the fuel IDs returned here when creating or updating vehicles.

Request

Headers

x-api-key · string · required

Your API key for authentication

Format: Your API key string

Response

array · array[object]

Array of fuel type objects

Show Fuel Object

id · string

Unique identifier (UUID) for the fuel type

fuel · string

Fuel type name (e.g., “diesel”, “petrol”, “electric”)

country · string

ISO 3166-1 two-letter country code for emission factors

fuel_units · array[object]

Units a consumption of this fuel accepts. Creating or updating a vehicle consumption (API or CSV upload) with any other unit for this fuel is refused with ERR_UNIT_NOT_ALLOWED_FOR_FUEL. Units the fuel cannot be calculated in are left out (e.g. kilogram_(kg) for battery_electric_vehicle).

Show Fuel Unit Object

id · string

Unique identifier (UUID) for the unit

name · string

Unit name (e.g., “liters”, “gallons”, “kg”, “kWh”)

type · string

Unit type/category (e.g., “volume”, “mass”, “energy”)

created_at · datetime

Timestamp when the fuel type was created

updated_at · datetime | null

Timestamp when the fuel type was last updated

Example

cURL

curl -X GET "https://api.dcycle.io/v1/vehicle-fuels" \
  -H "x-api-key: ${DCYCLE_API_KEY}"

Successful Response

[
  {
    "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"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "fuel": "petrol",
    "country": "ES",
    "fuel_units": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "liters",
        "type": "volume"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "fuel": "electric",
    "country": "ES",
    "fuel_units": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440003",
        "name": "kWh",
        "type": "energy"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active. Get a new one from Settings → API.

500 Internal Server Error

Cause: Server error retrieving fuel data

{
  "detail": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Solution: Contact support if the error persists.

Use Cases

Get All Fuels for Vehicle Creation

Retrieve available fuels before creating a vehicle:

def get_all_fuels():
    """Get all available fuel types"""
    response = requests.get(
        "https://api.dcycle.io/v1/vehicle-fuels",
        headers=headers
    )

    return response.json()

# Get all fuels
all_fuels = get_all_fuels()
print(f"Available fuels: {len(all_fuels)}")

# Find a specific fuel
diesel = next(f for f in all_fuels if f['fuel'] == 'diesel')
print(f"Diesel ID: {diesel['id']}")

Filter Fuels by Country

Get fuel types specific to a country:

def get_fuels_by_country(country_code):
    """Get fuel types 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_by_country("ES")
for fuel in spain_fuels:
    print(f"{fuel['fuel']}: {[u['name'] for u in fuel['fuel_units']]}")

Group Fuels by Type

Organize fuels for display:

def group_fuels_by_type():
    """Group all fuels by fuel type"""
    response = requests.get(
        "https://api.dcycle.io/v1/vehicle-fuels",
        headers=headers
    )

    fuels = response.json()
    grouped = {}

    for fuel in fuels:
        fuel_type = fuel['fuel']
        if fuel_type not in grouped:
            grouped[fuel_type] = []
        grouped[fuel_type].append({
            "id": fuel['id'],
            "country": fuel['country'],
            "units": fuel['fuel_units']
        })

    return grouped

# Get grouped fuels
fuels_by_type = group_fuels_by_type()
for fuel_type, entries in fuels_by_type.items():
    print(f"{fuel_type}: {len(entries)} countries")

Build Fuel Selection Dropdown

Create a user-friendly fuel selector:

def get_fuel_options_for_ui(country_code):
    """Get fuel options formatted for UI dropdown"""
    response = requests.get(
        "https://api.dcycle.io/v1/vehicle-fuels",
        headers=headers
    )

    fuels = response.json()
    options = []

    for fuel in fuels:
        if fuel['country'] == country_code:
            options.append({
                "label": fuel['fuel'].capitalize(),
                "value": fuel['id'],
                "units": [u['name'] for u in fuel['fuel_units']]
            })

    return options

# Get options for dropdown
fuel_options = get_fuel_options_for_ui("ES")
print("Fuel Options for Spain:")
for option in fuel_options:
    print(f"  {option['label']}: {option['value']}")
    print(f"    Units: {', '.join(option['units'])}")

Cache Fuel Data Locally

Cache fuel reference data to minimize API calls:

import json
from datetime import datetime, timedelta

class FuelCache:
    def __init__(self, cache_file="fuels_cache.json", ttl_hours=24):
        self.cache_file = cache_file
        self.ttl = timedelta(hours=ttl_hours)

    def is_valid(self):
        """Check if cache is still valid"""
        try:
            with open(self.cache_file, 'r') as f:
                data = json.load(f)
                cached_at = datetime.fromisoformat(data['cached_at'])
                return datetime.now() - cached_at < self.ttl
        except:
            return False

    def get(self):
        """Get cached fuels or fetch fresh data"""
        if self.is_valid():
            with open(self.cache_file, 'r') as f:
                return json.load(f)['fuels']

        # Fetch fresh data
        response = requests.get(
            "https://api.dcycle.io/v1/vehicle-fuels",
            headers=headers
        )
        fuels = response.json()

        # Cache it
        with open(self.cache_file, 'w') as f:
            json.dump({
                'fuels': fuels,
                'cached_at': datetime.now().isoformat()
            }, f)

        return fuels

# Use cache
cache = FuelCache()
fuels = cache.get()
print(f"Using {len(fuels)} cached fuel types")

Related Endpoints

Create Vehicle

Create vehicles with specific fuel types

Update Vehicle

Update vehicle fuel type

Unknown Vehicles

Browse vehicle type classifications

Vehicles API

Manage your vehicle fleet