> ## 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.
# Vehicle Fuels API
> Manage vehicle fuel types and their emission factors
# 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 an API key included in the `x-api-key` header.
## Headers
All requests should include:
Your API key for authentication
**Format:** Your API key string
## Available Endpoints
Retrieve all available fuel types with emission factors and units
## Fuel Types
Common fuel types include:
| Fuel Type | Description | Emission Factor (kg CO2e/unit) |
| --------------- | ------------------------ | ----------------------------------- |
| **Petrol** | Gasoline/benzine fuel | \~2.31 per liter |
| **Diesel** | Diesel fuel | \~2.68 per liter |
| **Electric** | Electric battery powered | \~0.0 per kWh (upstream) |
| **Hybrid** | Petrol-electric hybrid | \~1.5 per liter |
| **LPG** | Liquified petroleum gas | \~1.54 per kg |
| **Natural Gas** | Compressed natural gas | \~2.04 per kg |
| **Hydrogen** | Hydrogen fuel cell | \~0.0 per kg (production dependent) |
## Fuel Units
Fuel can be measured in various units:
| Unit | Type | Description |
| ---------- | ------ | ------------------------------------------ |
| **liter** | Volume | Standard fuel measurement for liquid fuels |
| **kg** | Mass | Used for gaseous and solid fuels |
| **kWh** | Energy | Used for electric vehicles |
| **gallon** | Volume | US/Imperial fuel measurement |
| **m³** | Volume | Cubic meters for gaseous fuels |
## Fuel Object Structure
```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"
}
```
## 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
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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
| Status | Meaning | Solution |
| ------ | ------------ | --------------------------- |
| 200 | Success | - |
| 401 | Unauthorized | Verify API key or JWT token |
| 500 | Server Error | Contact support if persists |
### Error Response Format
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"detail": "Error description",
"code": "ERROR_CODE"
}
```
## Use Cases
### Build Fuel Selection UI
Display available fuels in your application:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```
## Related Documentation
Create vehicles with specific fuel types
View vehicles and their fuel assignments
Browse vehicle type classifications
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