Skip to main content
GET
/
v1
/
vehicle-fuels
List Vehicle Fuels
const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

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

​
Authorization
string
required
Bearer token for authenticationFormat: Bearer {API_KEY} or Bearer {JWT_TOKEN}

​
Response

​
array
array[object]
Array of fuel type objects

​
Example

curl -X GET "https://api.dcycle.io/v1/vehicle-fuels" \
  -H "Authorization: Bearer ${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")

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