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

# Business Travels API

> Manage business travel records and calculate CO2e emissions for Scope 3 Category 6

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

<Note>
  **New API**: This endpoint is part of the new API architecture with improved design and maintainability.
</Note>

## 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 an API key included in the `x-api-key` header.

## Headers

All requests must include:

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

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

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

## Available Endpoints

<CardGroup cols={2}>
  <Card title="List Business Travels" icon="list" href="/api-reference/business-travels/list">
    Retrieve all business travels with filtering and pagination
  </Card>

  <Card title="Get Business Travel" icon="magnifying-glass" href="/api-reference/business-travels/get">
    Retrieve a specific business travel by ID
  </Card>

  <Card title="Create Business Travel" icon="plus" href="/api-reference/business-travels/create">
    Add a new business travel record
  </Card>

  <Card title="Update Business Travel" icon="pencil" href="/api-reference/business-travels/update">
    Modify business travel details
  </Card>

  <Card title="Delete Business Travel" icon="trash" href="/api-reference/business-travels/delete">
    Remove a business travel record
  </Card>
</CardGroup>

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

| Value        | Description            |
| ------------ | ---------------------- |
| `car`        | Personal or rental car |
| `train`      | Rail transport         |
| `aircraft`   | Air travel             |
| `bus`        | Bus transport          |
| `metro`      | Metro/subway           |
| `trolleybus` | Electric trolleybus    |
| `motorbike`  | Motorcycle             |
| `ferry`      | Ferry/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**

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "travel_date": "2024-12-01",
  "transport_type": "train",
  "origin": "Madrid, Spain",
  "destination": "Barcelona, Spain",
  "travel_number": 2
}
```

<Warning>
  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.
</Warning>

## Response Format

### Business Travel Object

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    { "business travel object" },
    { "business travel object" }
  ],
  "total": 150,
  "page": 1,
  "size": 50,
  "filter_hash": "a1b2c3d4e5f67890"
}
```

## Error Handling

### Common HTTP Status Codes

| Status | Meaning                        | Solution                            |
| ------ | ------------------------------ | ----------------------------------- |
| 200    | Success                        | -                                   |
| 201    | Created                        | -                                   |
| 204    | No Content (delete successful) | -                                   |
| 400    | Bad Request                    | Check request parameters and format |
| 401    | Unauthorized                   | Verify API key or JWT token         |
| 403    | Forbidden                      | Check organization limits           |
| 404    | Not Found                      | Check resource ID or organization   |
| 422    | Validation Error               | Review error details in response    |
| 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"
}
```

### Common Error Codes

| Code                        | Description                                              |
| --------------------------- | -------------------------------------------------------- |
| `LIMIT_REACHED`             | Organization has reached maximum business travel records |
| `BUSINESS_TRAVEL_NOT_FOUND` | Business travel record not found                         |
| `INVALID_TRAVEL_MODE`       | Transport type not valid for the specified route         |

## Use Cases

### Track Employee Travel Emissions

Monitor CO2e emissions for all business travel in your organization:

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

Evaluate emissions for different transport modes:

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

## Related Documentation

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to get your API key and authenticate requests
  </Card>

  <Card title="Employees API" icon="users" href="/api-reference/employees/overview">
    Manage employee data and commuting emissions (Scope 3 Category 7)
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Manage fleet vehicles and their emissions
  </Card>

  <Card title="Logistics API" icon="truck" href="/api-reference/logistics/overview">
    Calculate emissions for freight and logistics
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/business-travels">
    Query travel data from AI assistants via MCP
  </Card>
</CardGroup>

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