Get Transport Route

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/transports/{transport_route_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "name": {},
  "transport_date": "<string>",
  "quantity_transported": 123,
  "supplier": {},
  "transport_direction": "<string>",
  "transport_frequency": {},
  "unit": {
    "unit.id": "<string>",
    "unit.name": "<string>",
    "unit.type": "<string>"
  },
  "co2e": {},
  "emissions": [
    {}
  ],
  "status": "<string>",
  "file_id": {},
  "sections": [
    {}
  ],
  "created_at": {},
  "updated_at": {},
  "sections[].id": "<string>",
  "sections[].part": 123,
  "sections[].transport_type": "<string>",
  "sections[].travel_method": {},
  "sections[].electric": true,
  "sections[].refrigerated": true,
  "sections[].detail": {},
  "sections[].origin": "<string>",
  "sections[].destination": "<string>",
  "sections[].kms": {},
  "sections[].kms_manual": {},
  "sections[].distance_manual": true,
  "sections[].kms_source": {},
  "sections[].status": "<string>",
  "sections[].step": {},
  "sections[].error_messages": {},
  "sections[].emissions": {}
}

GET

transports

{transport_route_id}

Get Transport Route

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/transports/{transport_route_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "name": {},
  "transport_date": "<string>",
  "quantity_transported": 123,
  "supplier": {},
  "transport_direction": "<string>",
  "transport_frequency": {},
  "unit": {
    "unit.id": "<string>",
    "unit.name": "<string>",
    "unit.type": "<string>"
  },
  "co2e": {},
  "emissions": [
    {}
  ],
  "status": "<string>",
  "file_id": {},
  "sections": [
    {}
  ],
  "created_at": {},
  "updated_at": {},
  "sections[].id": "<string>",
  "sections[].part": 123,
  "sections[].transport_type": "<string>",
  "sections[].travel_method": {},
  "sections[].electric": true,
  "sections[].refrigerated": true,
  "sections[].detail": {},
  "sections[].origin": "<string>",
  "sections[].destination": "<string>",
  "sections[].kms": {},
  "sections[].kms_manual": {},
  "sections[].distance_manual": true,
  "sections[].kms_source": {},
  "sections[].status": "<string>",
  "sections[].step": {},
  "sections[].error_messages": {},
  "sections[].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

Authentication

Supports both authentication methods:

x-api-key

string

Your API key (use this or Authorization)Example: sk_live_1234567890abcdef

Authorization

string

Bearer JWT token (use this or x-api-key)Example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Headers

x-organization-id

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

transport_route_id

string

required

The unique identifier (UUID) of the transport routeExample: 010ed3b6-b513-40f3-b9fe-0f0a338d9274

Response

Route Fields

string

Unique identifier (UUID)

name

string | null

Optional route name

transport_date

date

Date of transport (YYYY-MM-DD). null if not set

quantity_transported

number

Amount transported (max 10 digits, 3 decimal places)

supplier

string | null

Optional supplier name

transport_direction

string

downstream (outbound — goods sent to customers) or upstream (inbound — goods received from suppliers)

transport_frequency

string | null

Recurrence: once, weekly, monthly

unit

object

Measurement unit for the quantity transported

Show unit fields

unit.id

string

UUID of the unit

unit.name

string

Unit name, e.g. kilogram_(kg), metric_tonne_(t)

unit.type

string

Unit type, e.g. solid, liquid

co2e

number | null

Total CO2-equivalent emissions in kg across all sections. null if no impacts have been calculated yet

emissions

array

Route-level emissions summary: [{"value": 245.67, "gas": "co2e", "unit_name": "kgCO2e"}]

status

string

Route status: pending (awaiting calculation), active (calculated), error (calculation failed)

file_id

string | null

ID of the uploaded file if this route was created via bulk upload

sections

array

List of transport sections (legs). See Section Fields below

created_at

datetime

ISO 8601 creation timestamp

updated_at

datetime

ISO 8601 last-update timestamp

Section Fields

sections[].id

string

Section UUID

sections[].part

integer

Sequence number within the route (1-based)

sections[].transport_type

string

road, air, maritime, rail, or do_not_know

sections[].travel_method

string | null

Sub-type for road transport: car, truck, motorbike, bicycle, electric_kick_scooter

sections[].electric

boolean

Whether the vehicle is electric

sections[].refrigerated

boolean

Whether the cargo is refrigerated

sections[].detail

string | null

Additional detail used for emission factor selection (e.g. distance band or weight class)

sections[].origin

string

Origin location address

sections[].destination

string

Destination location address

sections[].kms

number | null

Calculated or user-provided distance in kilometers

sections[].kms_manual

number | null

Distance override provided directly by the user (max 7 digits, 2 decimal places). Present when distance_manual is true

sections[].distance_manual

boolean

true when the distance was provided manually via kms_manual instead of being auto-calculated

sections[].kms_source

string | null

Method used to calculate the distance. See Distance Calculation Methods for all values

sections[].status

string

Section status: pending, active, error

sections[].step

string | null

Current processing step: geocoding, impact_calculation, completed

sections[].error_messages

array | null

List of error messages when status is error

sections[].emissions

array | null

CO2e emissions for this section: [{"value": 12.34, "gas": "co2e", "unit_name": "kgCO2e"}]

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

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.

Example

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}"

Successful Response

{
  "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,
  "sections": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "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",
      "error_messages": 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",
      "destination": "Latakia Port, Syria",
      "kms": 4626.0,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": "cerdi_sea_distance",
      "status": "active",
      "step": "completed",
      "error_messages": 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

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

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

{"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

{"detail": "TransportRoute not found", "code": "TRANSPORT_ROUTE_NOT_FOUND"}

List Transport Routes

Retrieve all transport routes with filtering and pagination

Create Transport Route

Create a new transport route with sections

Update Transport Route

Modify a transport route and its sections

Transport Overview

Full data model and distance calculation reference

Transport Type Inference (do_not_know)List Transport Routes

​Get Transport Route

​Request

​Authentication

​Headers

​Path Parameters

​Response

​Route Fields

​Section Fields

​Distance Calculation Methods

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

List Transport Routes

Create Transport Route

Update Transport Route

Transport Overview

Get Transport Route

Request

Authentication

Headers

Path Parameters

Response

Route Fields

Section Fields

Distance Calculation Methods

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints