Skip to main content

​
Business Travels API

The Business Travels API allows you to create, retrieve, update, and delete business travel records within your organization. Business travel emissions are part of Scope 3 Category 6 according to the GHG Protocol, covering employee travel for work-related activities.
New API: This endpoint is part of the new API architecture with improved design and maintainability.

​
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

All endpoints require authentication using either:
  • API Key: Include in Authorization header as Bearer {API_KEY}
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests must include:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
Authorization
string
required
Bearer token for authenticationFormat: Bearer {API_KEY} or Bearer {JWT_TOKEN}

​
Available Endpoints

List Business Travels

Retrieve all business travels with filtering and pagination

Get Business Travel

Retrieve a specific business travel by ID

Create Business Travel

Add a new business travel record

Update Business Travel

Modify business travel details

Delete Business Travel

Remove a business travel record

​
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

ValueDescription
carPersonal or rental car
trainRail transport
aircraftAir travel
busBus transport
metroMetro/subway
trolleybusElectric trolleybus
motorbikeMotorcycle
ferryFerry/boat

​
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

You can create business travel records in two ways: Option 1: With direct distance 
{
  "travel_date": "2024-12-01",
  "transport_type": "train",
  "distance_km": 350,
  "travel_number": 2,
  "round_trip": true
}
Option 2: With origin/destination (auto-calculate distance) 
{
  "travel_date": "2024-12-01",
  "transport_type": "train",
  "origin": "Madrid, Spain",
  "destination": "Barcelona, Spain",
  "travel_number": 2
}
You must provide either distance_km OR (origin AND destination), not both. If origin/destination are provided, distance will be calculated automatically using Google Maps routing.

​
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,
  "pages": 3
}

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success-
201Created-
204No Content (delete successful)-
400Bad RequestCheck request parameters and format
401UnauthorizedVerify API key or JWT token
403ForbiddenCheck organization limits
404Not FoundCheck resource ID or organization
422Validation ErrorReview error details in response
500Server ErrorContact support if persists

​
Error Response Format

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

​
Common Error Codes

CodeDescription
LIMIT_REACHEDOrganization has reached maximum business travel records
BUSINESS_TRAVEL_NOT_FOUNDBusiness travel record not found
INVALID_TRAVEL_MODETransport type not valid for the specified route

​
Use Cases

​
Track Employee Travel Emissions

Monitor CO2e emissions for all business travel in your organization: 
import requests

# Get all business travels for the year
travels = requests.get(
    "https://api.dcycle.io/v1/business-travels",
    headers={
        "Authorization": f"Bearer {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

Evaluate emissions for different transport modes: 
# 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

Business travel emissions fall under Scope 3, Category 6 of the GHG Protocol:
  • Scope 3: Indirect emissions from value chain activities
  • Category 6: Business Travel - emissions from employee travel for work purposes
This includes:
  • Air travel
  • Rail travel
  • Road travel (rental cars, taxis, personal vehicles used for business)
  • Other transport modes

Authentication Guide

Learn how to get your API key and authenticate requests

Employees API

Manage employee data and commuting emissions (Scope 3 Category 7)

Vehicles API

Manage fleet vehicles and their emissions

Logistics API

Calculate emissions for freight and logistics

​
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