Get Transport Route

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', '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));

import requests

url = "https://api.dcycle.io/v1/transports/{transport_route_id}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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": {},
  "file_name": {},
  "uploaded_by": {
    "id": "<string>",
    "first_name": {},
    "last_name": {},
    "profile_img_url": {}
  },
  "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[].origin_geocode": {
    "country_code": "<string>",
    "place_id": "<string>",
    "address_formatted": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "sections[].destination": "<string>",
  "sections[].destination_geocode": {
    "country_code": "<string>",
    "place_id": "<string>",
    "address_formatted": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "sections[].kms": {},
  "sections[].kms_manual": {},
  "sections[].distance_manual": true,
  "sections[].kms_source": {},
  "sections[].status": "<string>",
  "sections[].step": {},
  "sections[].error_messages": {},
  "sections[].reference_product": {},
  "sections[].emissions": {}
}

GET

transports

{transport_route_id}

Get Transport Route

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', '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));

import requests

url = "https://api.dcycle.io/v1/transports/{transport_route_id}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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": {},
  "file_name": {},
  "uploaded_by": {
    "id": "<string>",
    "first_name": {},
    "last_name": {},
    "profile_img_url": {}
  },
  "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[].origin_geocode": {
    "country_code": "<string>",
    "place_id": "<string>",
    "address_formatted": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "sections[].destination": "<string>",
  "sections[].destination_geocode": {
    "country_code": "<string>",
    "place_id": "<string>",
    "address_formatted": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "sections[].kms": {},
  "sections[].kms_manual": {},
  "sections[].distance_manual": true,
  "sections[].kms_source": {},
  "sections[].status": "<string>",
  "sections[].step": {},
  "sections[].error_messages": {},
  "sections[].reference_product": {},
  "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

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Path Parameters

string

required

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

Response

Route Fields

string

Unique identifier (UUID)

string | null

Optional route name

date

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

number

Amount transported (max 10 digits, 3 decimal places)

string | null

Optional supplier name

string

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

string | null

Recurrence: once, weekly, monthly

object

Measurement unit for the quantity transported

Show unit fields

string

UUID of the unit

string

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

string

Unit type, e.g. solid, liquid

number | null

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

array

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

string

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

string | null

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

string | null

Name of the uploaded file

object | string | null

User who created the route. Object with user details, or a UUID string for legacy records.

Show User Object

string

User UUID

string | null

First name

string | null

Last name

string | null

Profile image URL

array

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

datetime

ISO 8601 creation timestamp

datetime | null

ISO 8601 last-update timestamp

Section Fields

string

Section UUID

integer

Sequence number within the route (1-based)

string

road, air, maritime, rail, or do_not_know

string | null

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

boolean

Whether the vehicle is electric

boolean

Whether the cargo is refrigerated

string | null

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

string

Origin location address

object | null

Geocoded origin location

Show Geographic Point

string

ISO country code

string

Geocoder place identifier

string

Full formatted address

number

Latitude

number

Longitude

string

Destination location address

object | null

Geocoded destination location

Show Geographic Point

string

ISO country code

string

Geocoder place identifier

string

Full formatted address

number

Latitude

number

Longitude

number | null

Calculated or user-provided distance in kilometers

number | null

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

boolean

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

string | null

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

string

Section status: pending, active, error

string | null

Current processing step: geocoding, impact_calculation, completed

array | null

List of error messages when status is error

string | null

Emission factor reference product used for impact calculation

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

curl -X GET "https://api.dcycle.io/v1/transports/010ed3b6-b513-40f3-b9fe-0f0a338d9274" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

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']})"
    )

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})`
    );
  });
});

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

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

​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

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