​

Business Travels API

​

Key Features

• Travel Records Management: Create and manage business travel records
• Multiple Transport Modes: Support for cars, trains, aircraft, ferries, buses, metro, and more
• Automatic Distance Calculation: Optionally provide origin/destination to auto-calculate distances
• CO2e Calculation: Automatic emissions calculation based on transport type and distance
• Flexible Input: Provide either direct distance or origin/destination addresses
• Pagination Support: Efficiently retrieve large lists of business travels

​

Authentication

​

Headers

​

Available Endpoints

​

Business Travel Attributes

​

Core Information

• travel_date (date, required): Date of the business travel
• transport_type (string, required): Mode of transport used
• distance_km (number, optional): Distance traveled in kilometers
• origin (string, optional): Starting location address
• destination (string, optional): Ending location address
• travel_number (integer, optional): Number of travelers (1-1000)
• round_trip (boolean, optional): Whether this is a round trip

​

Transport Types

​

Vehicle Details (for car/motorbike)

• vehicle_size (string, optional): small, medium, large, average
• fuel_type (string, optional): petrol, diesel, cng, lpg, unknown, plug_in_hybrid_electric, battery_electric

​

Flight Details (for aircraft)

• flight_type (string, optional): domestic, short_haul_international, long_haul_international
• cabin_class (string, optional): economy, premium_economy, business, first, average

​

Status

• status (string, read-only): active, pending, error
• co2e (number, read-only): Calculated CO2 equivalent emissions in kg

​

Workflow

​

Creating a Business Travel Record

{
  "travel_date": "2024-12-01",
  "transport_type": "train",
  "distance_km": 350,
  "travel_number": 2,
  "round_trip": true
}

{
  "travel_date": "2024-12-01",
  "transport_type": "train",
  "origin": "Madrid, Spain",
  "destination": "Barcelona, Spain",
  "travel_number": 2
}

​

Response Format

​

Business Travel Object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "travel_date": "2024-12-01",
  "transport_type": "train",
  "distance_km": 621.5,
  "origin": "Madrid, Spain",
  "destination": "Barcelona, Spain",
  "travel_number": 2,
  "round_trip": false,
  "vehicle_size": null,
  "fuel_type": null,
  "flight_type": null,
  "cabin_class": null,
  "status": "active",
  "co2e": 24.86,
  "created_at": "2024-12-01T10:30:00Z",
  "updated_at": "2024-12-01T10:30:00Z"
}

​

Pagination Response

{
  "items": [
    { "business travel object" },
    { "business travel object" }
  ],
  "total": 150,
  "page": 1,
  "size": 50,
  "filter_hash": "a1b2c3d4e5f67890"
}

​

Error Handling

​

Common HTTP Status Codes

​

Error Response Format

{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

​

Common Error Codes

​

Use Cases

​

Track Employee Travel Emissions

import requests

# Get all business travels for the year
travels = requests.get(
    "https://api.dcycle.io/v1/business-travels",
    headers={
        "x-api-key": api_key,
        "x-organization-id": org_id
    },
    params={
        "start_date": "2024-01-01",
        "end_date": "2024-12-31",
        "status": ["active"]
    }
)

total_co2e = sum(t["co2e"] for t in travels.json()["items"])
print(f"Annual business travel emissions: {total_co2e} kg CO2e")

​

Compare Transport Options

# Calculate emissions for different travel options
options = [
    {"transport_type": "aircraft", "cabin_class": "economy"},
    {"transport_type": "train"},
    {"transport_type": "car", "fuel_type": "diesel"}
]

for option in options:
    travel = {
        "travel_date": "2024-12-01",
        "origin": "Madrid, Spain",
        "destination": "Paris, France",
        **option
    }
    response = requests.post(
        "https://api.dcycle.io/v1/business-travels",
        headers=headers,
        json=travel
    )
    data = response.json()
    print(f"{data['transport_type']}: {data['co2e']} kg CO2e")

​

GHG Protocol Context

• Scope 3: Indirect emissions from value chain activities
• Category 6: Business Travel - emissions from employee travel for work purposes

• Air travel
• Rail travel
• Road travel (rental cars, taxis, personal vehicles used for business)
• Other transport modes

​

Related Documentation

​

Rate Limiting

• X-RateLimit-Limit: Maximum requests per minute
• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: Unix timestamp when limit resets