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

# Get Transport Route

> Retrieve a specific transport route by ID, including all sections, distances, and emissions

# Get Transport Route

Retrieve a transport route by its unique identifier. The response includes all sections (legs), the calculated distance per section with the method used to compute it, and the CO2e emissions per section.

## Request

### Headers

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

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

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

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

### Path Parameters

<ParamField path="transport_route_id" type="string" required>
  The unique identifier (UUID) of the transport route

  **Example:** `010ed3b6-b513-40f3-b9fe-0f0a338d9274`
</ParamField>

## Response

### Route Fields

<ResponseField name="id" type="string">
  Unique identifier (UUID)
</ResponseField>

<ResponseField name="name" type="string | null">
  Optional route name
</ResponseField>

<ResponseField name="transport_date" type="date">
  Date of transport (YYYY-MM-DD). `null` if not set
</ResponseField>

<ResponseField name="quantity_transported" type="number">
  Amount transported (max 10 digits, 3 decimal places)
</ResponseField>

<ResponseField name="supplier" type="string | null">
  Optional supplier name
</ResponseField>

<ResponseField name="transport_direction" type="string">
  `downstream` (outbound — goods sent to customers) or `upstream` (inbound — goods received from suppliers)
</ResponseField>

<ResponseField name="transport_frequency" type="string | null">
  Recurrence: `once`, `weekly`, `monthly`
</ResponseField>

<ResponseField name="unit" type="object">
  Measurement unit for the quantity transported

  <Expandable title="unit fields">
    <ResponseField name="unit.id" type="string">UUID of the unit</ResponseField>
    <ResponseField name="unit.name" type="string">Unit name, e.g. `kilogram_(kg)`, `metric_tonne_(t)`</ResponseField>
    <ResponseField name="unit.type" type="string">Unit type, e.g. `solid`, `liquid`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="co2e" type="number | null">
  Total CO2-equivalent emissions in kg across all sections. `null` if no impacts have been calculated yet
</ResponseField>

<ResponseField name="emissions" type="array">
  Route-level emissions summary: `[{"value": 245.67, "gas": "co2e", "unit_name": "kgCO2e"}]`
</ResponseField>

<ResponseField name="status" type="string">
  Route status: `pending` (awaiting calculation), `active` (calculated), `error` (calculation failed)
</ResponseField>

<ResponseField name="file_id" type="string | null">
  UUID of the uploaded file if this route was created via bulk upload
</ResponseField>

<ResponseField name="file_name" type="string | null">
  Name of the uploaded file
</ResponseField>

<ResponseField name="uploaded_by" type="object | string | null">
  User who created the route. Object with user details, or a UUID string for legacy records.

  <Expandable title="User Object">
    <ResponseField name="id" type="string">User UUID</ResponseField>
    <ResponseField name="first_name" type="string | null">First name</ResponseField>
    <ResponseField name="last_name" type="string | null">Last name</ResponseField>
    <ResponseField name="profile_img_url" type="string | null">Profile image URL</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sections" type="array">
  List of transport sections (legs). See [Section Fields](#section-fields) below
</ResponseField>

<ResponseField name="created_at" type="datetime">
  ISO 8601 creation timestamp
</ResponseField>

<ResponseField name="updated_at" type="datetime | null">
  ISO 8601 last-update timestamp
</ResponseField>

### Section Fields

<ResponseField name="sections[].id" type="string">
  Section UUID
</ResponseField>

<ResponseField name="sections[].part" type="integer">
  Sequence number within the route (1-based)
</ResponseField>

<ResponseField name="sections[].transport_type" type="string">
  `road`, `air`, `maritime`, `rail`, or `do_not_know`
</ResponseField>

<ResponseField name="sections[].travel_method" type="string | null">
  Sub-type for road transport: `car`, `truck`, `motorbike`, `bicycle`, `electric_kick_scooter`
</ResponseField>

<ResponseField name="sections[].electric" type="boolean">
  Whether the vehicle is electric
</ResponseField>

<ResponseField name="sections[].refrigerated" type="boolean">
  Whether the cargo is refrigerated
</ResponseField>

<ResponseField name="sections[].detail" type="string | null">
  Additional detail used for emission factor selection (e.g. distance band or weight class)
</ResponseField>

<ResponseField name="sections[].origin" type="string">
  Origin location address
</ResponseField>

<ResponseField name="sections[].origin_geocode" type="object | null">
  Geocoded origin location

  <Expandable title="Geographic Point">
    <ResponseField name="country_code" type="string">ISO country code</ResponseField>
    <ResponseField name="place_id" type="string">Geocoder place identifier</ResponseField>
    <ResponseField name="address_formatted" type="string">Full formatted address</ResponseField>
    <ResponseField name="latitude" type="number">Latitude</ResponseField>
    <ResponseField name="longitude" type="number">Longitude</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sections[].destination" type="string">
  Destination location address
</ResponseField>

<ResponseField name="sections[].destination_geocode" type="object | null">
  Geocoded destination location

  <Expandable title="Geographic Point">
    <ResponseField name="country_code" type="string">ISO country code</ResponseField>
    <ResponseField name="place_id" type="string">Geocoder place identifier</ResponseField>
    <ResponseField name="address_formatted" type="string">Full formatted address</ResponseField>
    <ResponseField name="latitude" type="number">Latitude</ResponseField>
    <ResponseField name="longitude" type="number">Longitude</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sections[].kms" type="number | null">
  Calculated or user-provided distance in kilometers
</ResponseField>

<ResponseField name="sections[].kms_manual" type="number | null">
  Distance override provided directly by the user (max 7 digits, 2 decimal places). Present when `distance_manual` is `true`
</ResponseField>

<ResponseField name="sections[].distance_manual" type="boolean">
  `true` when the distance was provided manually via `kms_manual` instead of being auto-calculated
</ResponseField>

<ResponseField name="sections[].kms_source" type="string | null">
  Method used to calculate the distance. See [Distance Calculation Methods](#distance-calculation-methods) for all values
</ResponseField>

<ResponseField name="sections[].status" type="string">
  Section status: `pending`, `active`, `error`
</ResponseField>

<ResponseField name="sections[].step" type="string | null">
  Current processing step: `geocoding`, `impact_calculation`, `completed`
</ResponseField>

<ResponseField name="sections[].error_messages" type="array | null">
  List of error messages when `status` is `error`
</ResponseField>

<ResponseField name="sections[].reference_product" type="string | null">
  Emission factor reference product used for impact calculation
</ResponseField>

<ResponseField name="sections[].emissions" type="array | null">
  CO2e emissions for this section: `[{"value": 12.34, "gas": "co2e", "unit_name": "kgCO2e"}]`
</ResponseField>

## Distance Calculation Methods

The `kms_source` field tells you exactly how the distance for a section was determined:

| Value                            | Transport type  | Description                                                                                                              |
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `cerdi_sea_distance`             | maritime        | Country-pair formula from the CERDI dataset: sea route between main ports + capital-to-port land legs for both countries |
| `searoute_sea_distance`          | maritime        | Navigable-water graph for same-country sea routes (e.g. mainland Spain → Canary Islands)                                 |
| `haversine_sea_distance`         | maritime        | Haversine great-circle fallback for same-country maritime when the graph is unavailable                                  |
| `haversine_formula`              | air             | Great-circle distance between geocoded coordinates                                                                       |
| `google_maps_distance_matrix_v1` | road / rail     | Google Maps Distance Matrix API                                                                                          |
| `aws_location_route_matrix`      | road / rail     | AWS Location Service (alternative to Google Maps)                                                                        |
| `default`                        | maritime / road | Hardcoded fallback: 500 km for same-country maritime, 3 km for same-place road                                           |
| `manual`                         | any             | User provided the distance directly via `kms_manual`                                                                     |
| `null`                           | any             | Not available — section pre-dates geocoding, or geocoding failed                                                         |

<Note>
  **Why does a Spain → Syria maritime section show 4626 km?**

  CERDI is a country-level dataset. The 4626 km is composed of three fixed values for the `ESP → SYR` pair:

  * **3761 km** — sea route between Spain's and Syria's representative ports
  * **655 km** — land distance from Madrid (Spain's capital) to its main sea port
  * **210 km** — land distance from Damascus (Syria's capital) to its main sea port

  This means every maritime shipment between any Spanish location and any Syrian location
  receives the same 4626 km distance, regardless of the specific cities involved.
  If you need a more precise distance, set `kms_manual` when creating the section.
</Note>

## Example

<CodeGroup>
  ```bash cURL (API Key) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/transports/010ed3b6-b513-40f3-b9fe-0f0a338d9274" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

  ```bash cURL (JWT) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/transports/010ed3b6-b513-40f3-b9fe-0f0a338d9274" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

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

  route_id = "010ed3b6-b513-40f3-b9fe-0f0a338d9274"

  response = requests.get(
      f"https://api.dcycle.io/v1/transports/{route_id}",
      headers={
          "x-api-key": os.getenv("DCYCLE_API_KEY"),
          "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
      },
  )

  route = response.json()
  print(f"Route: {route['name']}, CO2e: {route['co2e']} kgCO2e")
  for section in route["sections"]:
      print(
          f"  Section {section['part']}: {section['origin']} → {section['destination']} "
          f"| {section['kms']} km (source: {section['kms_source']})"
      )
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const routeId = '010ed3b6-b513-40f3-b9fe-0f0a338d9274';

  axios.get(`https://api.dcycle.io/v1/transports/${routeId}`, {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
  })
  .then(({ data: route }) => {
    console.log(`Route: ${route.name}, CO2e: ${route.co2e} kgCO2e`);
    route.sections.forEach(s => {
      console.log(
        `  Section ${s.part}: ${s.origin} → ${s.destination} | ${s.kms} km (source: ${s.kms_source})`
      );
    });
  });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "010ed3b6-b513-40f3-b9fe-0f0a338d9274",
  "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,
  "emissions": [{"value": 245.67, "gas": "co2e", "unit_name": "kgCO2e"}],
  "status": "active",
  "file_id": null,
  "file_name": null,
  "uploaded_by": {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "first_name": "Ana",
    "last_name": "García",
    "profile_img_url": null
  },
  "sections": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "part": 1,
      "transport_type": "road",
      "travel_method": "truck",
      "electric": false,
      "refrigerated": false,
      "detail": null,
      "origin": "Madrid, Spain",
      "origin_geocode": {
        "country_code": "ES",
        "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ",
        "address_formatted": "Madrid, Spain",
        "latitude": 40.4168,
        "longitude": -3.7038
      },
      "destination": "Barcelona Port, Spain",
      "destination_geocode": {
        "country_code": "ES",
        "place_id": "ChIJ5TCOcRaYpBIRCmZHTz37sEQ",
        "address_formatted": "Barcelona, Spain",
        "latitude": 41.3874,
        "longitude": 2.1686
      },
      "kms": 145.0,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": "google_maps_distance_matrix_v1",
      "status": "active",
      "step": "completed",
      "error_messages": null,
      "reference_product": null,
      "emissions": [{"value": 12.34, "gas": "co2e", "unit_name": "kgCO2e"}],
      "created_at": "2024-06-10T09:00:00Z",
      "updated_at": "2024-06-15T14:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "part": 2,
      "transport_type": "maritime",
      "travel_method": null,
      "electric": false,
      "refrigerated": false,
      "detail": "ship_container",
      "origin": "Barcelona Port, Spain",
      "origin_geocode": null,
      "destination": "Latakia Port, Syria",
      "destination_geocode": null,
      "kms": 4626.0,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": "cerdi_sea_distance",
      "status": "active",
      "step": "completed",
      "error_messages": null,
      "reference_product": null,
      "emissions": [{"value": 233.33, "gas": "co2e", "unit_name": "kgCO2e"}],
      "created_at": "2024-06-10T09:00:00Z",
      "updated_at": "2024-06-15T14:30:00Z"
    }
  ],
  "created_at": "2024-06-10T09:00:00Z",
  "updated_at": "2024-06-15T14:30:00Z"
}
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key / JWT token

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

**Cause:** The authenticated user is not a member of the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
```

### 404 Not Found

**Cause:** Route ID does not exist or belongs to a different organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "TransportRoute not found", "code": "TRANSPORT_ROUTE_NOT_FOUND"}
```

## Related Endpoints

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

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

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

  <Card title="Transport Overview" icon="book" href="/api-reference/transport/overview">
    Full data model and distance calculation reference
  </Card>
</CardGroup>