> ## 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 Vehicle Fuels

> Retrieve all available fuel types with emission factors and units

# 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.

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

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Format:** Your API key string
</ParamField>

## Response

<ResponseField name="array" type="array[object]">
  Array of fuel type objects

  <Expandable title="Fuel Object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID) for the fuel type
    </ResponseField>

    <ResponseField name="fuel" type="string">
      Fuel type name (e.g., "diesel", "petrol", "electric")
    </ResponseField>

    <ResponseField name="country" type="string">
      ISO 3166-1 two-letter country code for emission factors
    </ResponseField>

    <ResponseField name="fuel_units" type="array[object]">
      Available units for this fuel type

      <Expandable title="Fuel Unit Object">
        <ResponseField name="id" type="string">
          Unique identifier (UUID) for the unit
        </ResponseField>

        <ResponseField name="name" type="string">
          Unit name (e.g., "liters", "gallons", "kg", "kWh")
        </ResponseField>

        <ResponseField name="type" type="string">
          Unit type/category (e.g., "volume", "mass", "energy")
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Timestamp when the fuel type was created
    </ResponseField>

    <ResponseField name="updated_at" type="datetime | null">
      Timestamp when the fuel type was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/vehicle-fuels" \
    -H "x-api-key: ${DCYCLE_API_KEY}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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']})")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

**Solution:** Verify your API key is valid and active. Get a new one from [Settings → API](https://app.dcycle.io/settings/api).

### 500 Internal Server Error

**Cause:** Server error retrieving fuel data

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<CardGroup cols={2}>
  <Card title="Create Vehicle" icon="plus" href="/api-reference/vehicles/create">
    Create vehicles with specific fuel types
  </Card>

  <Card title="Update Vehicle" icon="pencil" href="/api-reference/vehicles/update">
    Update vehicle fuel type
  </Card>

  <Card title="Unknown Vehicles" icon="question" href="/api-reference/unknown-vehicles/overview">
    Browse vehicle type classifications
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Manage your vehicle fleet
  </Card>
</CardGroup>