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

# Transport API

> Manage upstream and downstream transport routes with multi-section legs, emissions calculations, and bulk operations

# Transport API

The Transport API lets you create and manage transport routes for tracking Scope 3 upstream and downstream transportation emissions. Each route can have multiple sections (legs) with different transport types, and emissions are automatically calculated using ecoinvent emission factors.

<Note>
  **New API**: These endpoints are part of the new API architecture and replace the legacy `transport_routes` and `transport_sections` endpoints.
</Note>

## Key Features

* **Multi-Section Routes**: Define routes with multiple transport legs (e.g., truck to port, ship overseas, truck to warehouse)
* **Automatic Emissions Calculation**: CO2e emissions calculated per section using ecoinvent factors
* **Automatic Distance Calculation**: Distances computed via CERDI (maritime), Google Maps (road/rail), or haversine formula (air) — or provided manually
* **Bulk Operations**: Upload routes via CSV/Excel or delete in bulk by IDs or filters
* **Presigned URL Uploads**: Upload large files directly to S3 via presigned URLs
* **Version History**: Track changes to transport routes over time
* **Flexible Filtering**: Filter by date, status, direction, file, and CO2e calculation status

## Authentication

All endpoints support both authentication methods:

* **API Key**: Include in `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">
  Your API key for authentication (use this **or** `Authorization`)

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

## Available Endpoints

### Transport Route Management

<CardGroup cols={2}>
  <Card title="List Transport Routes" icon="list" href="/api-reference/transport/list">
    Retrieve all transport routes with filtering, sorting, and pagination
  </Card>

  <Card title="Get Transport Route" icon="route" href="/api-reference/transport/get">
    Get a specific transport route by ID with all sections and emissions
  </Card>

  <Card title="Create Transport Route" icon="plus" href="/api-reference/transport/create">
    Create a new transport route with one or more sections
  </Card>

  <Card title="Update Transport Route" icon="pencil" href="/api-reference/transport/update">
    Modify a transport route and its sections
  </Card>

  <Card title="Delete Transport Route" icon="trash" href="/api-reference/transport/delete">
    Remove a transport route
  </Card>

  <Card title="Get Route Counts" icon="chart-bar" href="/api-reference/transport/counts">
    Get aggregate counts by status (pending, active, error)
  </Card>
</CardGroup>

### Bulk Operations

<CardGroup cols={2}>
  <Card title="Upload File" icon="upload" href="/api-reference/transport/upload">
    Upload transport routes via CSV/Excel file
  </Card>

  <Card title="Presigned URL Upload" icon="cloud-arrow-up" href="/api-reference/transport/presigned-url">
    Get a presigned S3 URL for large file uploads
  </Card>

  <Card title="Bulk Delete by IDs" icon="trash-can" href="/api-reference/transport/bulk-delete">
    Delete up to 100,000 transport routes by ID
  </Card>

  <Card title="Bulk Delete by Filters" icon="filter" href="/api-reference/transport/bulk-delete-by-filters">
    Delete all routes matching filter criteria
  </Card>
</CardGroup>

### Reference Data

<CardGroup cols={2}>
  <Card title="Transport Combinations" icon="shuffle" href="/api-reference/transport/combinations">
    Get valid transport type/method combinations
  </Card>

  <Card title="Version History" icon="clock-rotate-left" href="/api-reference/transport/versions">
    View change history for a transport route
  </Card>

  <Card title="do_not_know Inference" icon="question" href="/api-reference/transport/do-not-know-inference">
    How Dcycle infers transport mode and distance automatically
  </Card>
</CardGroup>

## Data Model

### Transport Route Object

A transport route represents a shipment with one or more transport sections (legs):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Madrid to Syria Shipment",
  "transport_date": "2024-06-15",
  "quantity_transported": 1500.0,
  "supplier": "LogiTrans S.A.",
  "transport_direction": "downstream",
  "transport_frequency": null,
  "unit": {
    "id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
    "name": "kilogram_(kg)",
    "type": "solid"
  },
  "co2e": 245.67,
  "status": "active",
  "sections": [
    {
      "id": "section-uuid-001",
      "part": 1,
      "transport_type": "road",
      "travel_method": "truck",
      "electric": false,
      "refrigerated": false,
      "detail": null,
      "origin": "Madrid, Spain",
      "destination": "Barcelona Port, Spain",
      "kms": 145.0,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": "google_maps_distance_matrix_v1",
      "status": "active",
      "step": "completed",
      "emissions": [
        {"value": 12.34, "gas": "co2e", "unit_name": "kgCO2e"}
      ]
    },
    {
      "id": "section-uuid-002",
      "part": 2,
      "transport_type": "maritime",
      "travel_method": null,
      "electric": false,
      "refrigerated": false,
      "detail": "ship_container",
      "origin": "Barcelona Port, Spain",
      "destination": "Latakia Port, Syria",
      "kms": 4626.0,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": "cerdi_sea_distance",
      "status": "active",
      "step": "completed",
      "emissions": [
        {"value": 233.33, "gas": "co2e", "unit_name": "kgCO2e"}
      ]
    }
  ],
  "file_id": null,
  "created_at": "2024-06-10T09:00:00Z",
  "updated_at": "2024-06-15T14:30:00Z"
}
```

### Transport Route Attributes

| Field                  | Type           | Description                                                                    |
| ---------------------- | -------------- | ------------------------------------------------------------------------------ |
| `id`                   | UUID           | Unique identifier                                                              |
| `name`                 | string \| null | Optional route name                                                            |
| `transport_date`       | date           | Date of transport (YYYY-MM-DD)                                                 |
| `quantity_transported` | decimal        | Amount transported (max 10 digits, 3 decimal places)                           |
| `supplier`             | string \| null | Optional supplier name                                                         |
| `transport_direction`  | string         | `downstream` (outbound to customers) or `upstream` (inbound from suppliers)    |
| `transport_frequency`  | string \| null | Recurrence: `once`, `weekly`, `monthly`                                        |
| `unit`                 | object         | Measurement unit for quantity                                                  |
| `co2e`                 | float \| null  | Calculated CO2-equivalent emissions in kg. `null` if no impacts calculated yet |
| `status`               | string         | Route status: `pending`, `active`, `error`                                     |
| `sections`             | array          | List of transport sections (legs)                                              |
| `file_id`              | UUID \| null   | ID of the uploaded file (if bulk-uploaded)                                     |
| `created_at`           | datetime       | Creation timestamp                                                             |
| `updated_at`           | datetime       | Last update timestamp                                                          |

### Transport Section Attributes

| Field             | Type           | Description                                                                                          |
| ----------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| `id`              | UUID           | Section identifier                                                                                   |
| `part`            | integer        | Sequence number within the route (1-based)                                                           |
| `transport_type`  | string         | See [Transport Types](#transport-types)                                                              |
| `travel_method`   | string \| null | Sub-type for road: `car`, `truck`, `motorbike`, `bicycle`, `electric_kick_scooter`                   |
| `electric`        | boolean        | Whether the vehicle is electric                                                                      |
| `refrigerated`    | boolean        | Whether the cargo is refrigerated                                                                    |
| `detail`          | string \| null | Additional detail category (used for emission factor selection)                                      |
| `origin`          | string         | Origin location address                                                                              |
| `destination`     | string         | Destination location address                                                                         |
| `kms`             | float \| null  | Calculated distance in kilometers                                                                    |
| `kms_manual`      | float \| null  | User-provided distance override (max 7 digits, 2 decimal places)                                     |
| `distance_manual` | boolean        | `true` when `kms_manual` was used instead of auto-calculation                                        |
| `kms_source`      | string \| null | Method used to calculate distance. See [Distance Calculation Methods](#distance-calculation-methods) |
| `status`          | string         | Section status: `pending`, `active`, `error`                                                         |
| `step`            | string \| null | Current processing step: `geocoding`, `impact_calculation`, `completed`                              |
| `error_messages`  | array \| null  | List of error messages if `status` is `error`                                                        |
| `emissions`       | array \| null  | CO2e emissions per gas: `[{"value": 12.34, "gas": "co2e", "unit_name": "kgCO2e"}]`                   |

## Transport Types

| Value         | Description                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `road`        | Road freight transport (truck, car, etc.)                                                           |
| `air`         | Air freight                                                                                         |
| `maritime`    | Sea freight (container ship, tanker, etc.)                                                          |
| `rail`        | Rail freight                                                                                        |
| `do_not_know` | Unknown transport type — system infers road, maritime, or air based on origin/destination countries |

## Distance Calculation Methods

The `kms_source` field on each section tells you how the distance was determined:

| Value                            | Description                                                                                                       |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `cerdi_sea_distance`             | Maritime, different countries — CERDI country-pair formula: port-to-port sea distance + capital-to-port land legs |
| `searoute_sea_distance`          | Maritime, same country — navigable-water graph (e.g. mainland Spain → Canary Islands)                             |
| `haversine_sea_distance`         | Maritime, same country — haversine fallback when searoute is unavailable                                          |
| `haversine_formula`              | Air transport — great-circle distance between geocoded points                                                     |
| `google_maps_distance_matrix_v1` | Road or rail — Google Maps Distance Matrix API                                                                    |
| `aws_location_route_matrix`      | Road or rail — AWS Location Service (alternative to Google Maps)                                                  |
| `default`                        | Same-country maritime (500 km hardcoded) or same-place road (3 km hardcoded)                                      |
| `manual`                         | Distance provided directly by the user via `kms_manual`                                                           |
| `null`                           | Not available — section was created before geocoding was introduced, or geocoding failed                          |

<Note>
  **CERDI distance explained**: For maritime routes between different countries, the distance
  is calculated as the sum of three components from the CERDI dataset:
  the sea route between the countries' main ports, the land distance from the origin country's
  capital to its main port, and the land distance from the destination country's capital to its
  main port. This is a country-level approximation — all shipments between two countries
  receive the same maritime distance regardless of the specific origin/destination city.
</Note>

## 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                      | Verify the user has access to the organization |
| 404    | Not Found                      | Check resource ID or organization              |
| 422    | Validation Error               | Review error details in response               |
| 500    | Server Error                   | Contact support if persists                    |

## Common Use Cases

### Create a multi-leg shipment

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v1/transports" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Madrid to Berlin via Paris",
      "transport_date": "2024-06-15",
      "quantity_transported": 1500,
      "transport_direction": "downstream",
      "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
      "sections": [
        {
          "transport_type": "road",
          "travel_method": "truck",
          "origin": "Madrid, Spain",
          "destination": "Paris, France",
          "electric": false,
          "refrigerated": false
        },
        {
          "transport_type": "rail",
          "origin": "Paris, France",
          "destination": "Berlin, Germany",
          "electric": true,
          "refrigerated": false
        }
      ]
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  response = requests.post(
      "https://api.dcycle.io/v1/transports",
      headers={
          "x-api-key": os.getenv("DCYCLE_API_KEY"),
          "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
      },
      json={
          "name": "Madrid to Berlin via Paris",
          "transport_date": "2024-06-15",
          "quantity_transported": 1500,
          "transport_direction": "downstream",
          "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
          "sections": [
              {
                  "transport_type": "road",
                  "travel_method": "truck",
                  "origin": "Madrid, Spain",
                  "destination": "Paris, France",
                  "electric": False,
                  "refrigerated": False,
              },
              {
                  "transport_type": "rail",
                  "origin": "Paris, France",
                  "destination": "Berlin, Germany",
                  "electric": True,
                  "refrigerated": False,
              },
          ],
      },
  )

  transport = response.json()
  print(f"Route created: {transport['id']}, CO2e: {transport['co2e']} kgCO2e")
  ```
</CodeGroup>

### Upload transport data via presigned URL

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}

# Step 1: Get presigned URL
presigned = requests.post(
    "https://api.dcycle.io/v1/transports/upload/presigned-url",
    headers=headers,
    json={
        "file_name": "transport_data_q2.xlsx",
        "transport_direction": "downstream",
    },
).json()

# Step 2: Upload file directly to S3
with open("transport_data_q2.xlsx", "rb") as f:
    requests.put(presigned["upload_url"], data=f)

print(f"File uploaded. File ID: {presigned['file_id']}")
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Logistics API" icon="truck" href="/api-reference/logistics/overview">
    Manage logistics operations (GLEC Framework)
  </Card>

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

  <Card title="GHG Protocol Scope 3" icon="leaf" href="/guides/emissions/ghg-protocol-step-4-scope-3">
    Scope 3 upstream/downstream transport guide
  </Card>

  <Card title="ISO 14064 Category 3" icon="certificate" href="/guides/emissions/iso-14064-category-3-transportation">
    ISO 14064 transportation emissions guide
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/transports">
    Query transport records from AI assistants via MCP
  </Card>
</CardGroup>