List Vehicle Fuels

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));

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

GET

vehicle-fuels

List Vehicle Fuels

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));

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

List Vehicle Fuels

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

string

required

Your API key for authenticationFormat: Your API key string

Response

array[object]

Array of fuel type objects

Show Fuel Object

string

Unique identifier (UUID) for the fuel type

string

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

string

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

array[object]

Available units for this fuel type

Show Fuel Unit Object

string

Unique identifier (UUID) for the unit

string

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

string

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

datetime

Timestamp when the fuel type was created

datetime | null

Timestamp when the fuel type was last updated

Example

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

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")

headers = {
    "x-api-key": api_key
}

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

fuels = response.json()
for fuel in fuels:
    print(f"{fuel['fuel']} ({fuel['country']}): {fuel['id']}")
    for unit in fuel['fuel_units']:
        print(f"  - {unit['name']} ({unit['type']})")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;

const headers = {
  'x-api-key': apiKey
};

axios.get(
  'https://api.dcycle.io/v1/vehicle-fuels',
  { headers }
)
.then(response => {
  response.data.forEach(fuel => {
    console.log(`${fuel.fuel} (${fuel.country}): ${fuel.id}`);
    fuel.fuel_units.forEach(unit => {
      console.log(`  - ${unit.name} (${unit.type})`);
    });
  });
})
.catch(error => console.error(error));

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

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

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

​List Vehicle Fuels

​Request

​Headers

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​500 Internal Server Error

​Use Cases

​Get All Fuels for Vehicle Creation

​Filter Fuels by Country

​Group Fuels by Type

​Build Fuel Selection Dropdown

​Cache Fuel Data Locally

​Related Endpoints

Create Vehicle

Update Vehicle

Unknown Vehicles

Vehicles API

List Vehicle Fuels

Request

Headers

Response

Example

Successful Response

Common Errors

401 Unauthorized

500 Internal Server Error

Use Cases

Get All Fuels for Vehicle Creation

Filter Fuels by Country

Group Fuels by Type

Build Fuel Selection Dropdown

Cache Fuel Data Locally

Related Endpoints