List Transport Routes

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

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

import requests

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

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

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

print(response.text)

{
  "items": [
    {}
  ],
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "select_all_matching_enabled": true,
  "items[].id": "<string>",
  "items[].name": {},
  "items[].transport_date": {},
  "items[].quantity_transported": 123,
  "items[].supplier": {},
  "items[].transport_direction": "<string>",
  "items[].transport_frequency": {},
  "items[].unit": {
    "items[].unit.id": "<string>",
    "items[].unit.name": "<string>",
    "items[].unit.type": "<string>"
  },
  "items[].co2e": {},
  "items[].emissions": [
    {}
  ],
  "items[].status": "<string>",
  "items[].file_id": {},
  "items[].file_name": {},
  "items[].sections": [
    {}
  ],
  "items[].uploaded_by": {
    "items[].uploaded_by.id": "<string>",
    "items[].uploaded_by.first_name": {},
    "items[].uploaded_by.last_name": {},
    "items[].uploaded_by.profile_img_url": {}
  },
  "items[].created_at": {},
  "items[].updated_at": {},
  "items[].sections[].id": "<string>",
  "items[].sections[].part": 123,
  "items[].sections[].transport_type": "<string>",
  "items[].sections[].travel_method": {},
  "items[].sections[].electric": true,
  "items[].sections[].refrigerated": true,
  "items[].sections[].detail": {},
  "items[].sections[].origin": "<string>",
  "items[].sections[].origin_geocode": {
    "country_code": "<string>",
    "place_id": "<string>",
    "address_formatted": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "items[].sections[].destination": "<string>",
  "items[].sections[].destination_geocode": {
    "country_code": "<string>",
    "place_id": "<string>",
    "address_formatted": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "items[].sections[].kms": {},
  "items[].sections[].kms_manual": {},
  "items[].sections[].distance_manual": true,
  "items[].sections[].kms_source": {},
  "items[].sections[].status": "<string>",
  "items[].sections[].step": {},
  "items[].sections[].error_messages": {},
  "items[].sections[].reference_product": {},
  "items[].sections[].emissions": {}
}

GET

transports

List Transport Routes

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

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

import requests

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

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

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

print(response.text)

{
  "items": [
    {}
  ],
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "select_all_matching_enabled": true,
  "items[].id": "<string>",
  "items[].name": {},
  "items[].transport_date": {},
  "items[].quantity_transported": 123,
  "items[].supplier": {},
  "items[].transport_direction": "<string>",
  "items[].transport_frequency": {},
  "items[].unit": {
    "items[].unit.id": "<string>",
    "items[].unit.name": "<string>",
    "items[].unit.type": "<string>"
  },
  "items[].co2e": {},
  "items[].emissions": [
    {}
  ],
  "items[].status": "<string>",
  "items[].file_id": {},
  "items[].file_name": {},
  "items[].sections": [
    {}
  ],
  "items[].uploaded_by": {
    "items[].uploaded_by.id": "<string>",
    "items[].uploaded_by.first_name": {},
    "items[].uploaded_by.last_name": {},
    "items[].uploaded_by.profile_img_url": {}
  },
  "items[].created_at": {},
  "items[].updated_at": {},
  "items[].sections[].id": "<string>",
  "items[].sections[].part": 123,
  "items[].sections[].transport_type": "<string>",
  "items[].sections[].travel_method": {},
  "items[].sections[].electric": true,
  "items[].sections[].refrigerated": true,
  "items[].sections[].detail": {},
  "items[].sections[].origin": "<string>",
  "items[].sections[].origin_geocode": {
    "country_code": "<string>",
    "place_id": "<string>",
    "address_formatted": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "items[].sections[].destination": "<string>",
  "items[].sections[].destination_geocode": {
    "country_code": "<string>",
    "place_id": "<string>",
    "address_formatted": "<string>",
    "latitude": 123,
    "longitude": 123
  },
  "items[].sections[].kms": {},
  "items[].sections[].kms_manual": {},
  "items[].sections[].distance_manual": true,
  "items[].sections[].kms_source": {},
  "items[].sections[].status": "<string>",
  "items[].sections[].step": {},
  "items[].sections[].error_messages": {},
  "items[].sections[].reference_product": {},
  "items[].sections[].emissions": {}
}

Retrieve all transport routes for your organization. Supports full-text search, date range filters, status filters, and sorting. The response includes a filter_hash you can pass to the bulk-delete-by-filters endpoint to delete all matching records at once.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Query Parameters

string

Free-text search across route names, suppliers, and addresses. Minimum 1 character, maximum 255 characters.

date

Filter routes with transport_date on or after this date (YYYY-MM-DD)

date

Filter routes with transport_date on or before this date (YYYY-MM-DD)

array of string

Filter by route status. Allowed values: pending, active, error. Pass multiple values to include more than one status.

string

Filter by direction: downstream (outbound — goods sent to customers) or upstream (inbound — goods received from suppliers)

array of UUID

Filter by the uploaded file(s) that created these routes. Pass multiple UUIDs to include routes from several files.

datetime

Filter routes created on or after this timestamp (ISO 8601)

datetime

Filter routes created on or before this timestamp (ISO 8601)

string

Filter by emission calculation state: calculated (co2e is present) or not_calculated (co2e is null)

array of string

Filter by supplier name (exact match). Pass multiple values to include routes from several suppliers.

array of string

Sort fields. Prefix with - for descending order. Allowed fields: name, start_date, quantity_transported, created_at.Example: -created_at (newest first), start_date (oldest first)

integer

default:"1"

Page number (1-based)

integer

default:"50"

Number of results per page

Response

array

List of transport routes on this page. See Route Fields below.

integer

Total number of routes matching the current filters (across all pages)

integer

Current page number

integer

Number of items per page

string

Opaque hash representing the current filter state. Pass this value to the bulk-delete-by-filters endpoint to delete all routes matching the current query without specifying IDs individually.

boolean

Capability flag: true means this backend exposes the bulk-*-by-filters endpoint for this list, so the client may offer “select all matching”. false on a backend that only supports bulk delete by explicit ids.

Route Fields

string

Unique identifier (UUID)

string | null

Optional route name

date | null

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

number

Amount transported (up to 999,999,999.99999: 9 integer digits, 5 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. When the organization calculates the well-to-tank of goods transport (calculation preferences, wtt_transport_distribution_enabled), it includes each section’s well-to-tank (fuel production) emissions, reported under the same GHG Protocol category as the transport.

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

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

string | null

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

array

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

object | null

User who uploaded this route

Show uploaded_by fields

string

User ID

string | null

First name

string | null

Last name

string | null

Profile image URL

datetime

ISO 8601 creation timestamp

datetime

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 by the user (up to 8 integer digits, 6 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 compute the distance. See the Transport Overview 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 (transport plus its well-to-tank leg when calculated): [{"value": 12.34, "gas": "co2e", "unit_name": "kgCO2e"}]

Example

curl -X GET "https://api.dcycle.io/v1/transports?status=active&transport_direction=downstream&page=1&size=20" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

curl -X GET "https://api.dcycle.io/v1/transports?status=active&transport_direction=downstream&page=1&size=20" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

response = requests.get(
    "https://api.dcycle.io/v1/transports",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    },
    params={
        "status": ["active", "pending"],
        "transport_direction": "downstream",
        "from_date": "2024-01-01",
        "to_date": "2024-12-31",
        "sort": "-created_at",
        "page": 1,
        "size": 20,
    },
)

data = response.json()
print(f"Total routes: {data['total']}")
for route in data["items"]:
    print(f"  {route['name']} | {route['transport_date']} | CO2e: {route['co2e']} kgCO2e")

const axios = require('axios');

axios.get('https://api.dcycle.io/v1/transports', {
  headers: {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
  },
  params: {
    status: ['active', 'pending'],
    transport_direction: 'downstream',
    from_date: '2024-01-01',
    to_date: '2024-12-31',
    sort: '-created_at',
    page: 1,
    size: 20,
  },
})
.then(({ data }) => {
  console.log(`Total routes: ${data.total}`);
  data.items.forEach(route => {
    console.log(`  ${route.name} | ${route.transport_date} | CO2e: ${route.co2e} kgCO2e`);
  });
});

Successful Response

{
  "items": [
    {
      "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,
      "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"
        }
      ],
      "uploaded_by": {
        "id": "user-123",
        "first_name": "Maria",
        "last_name": "García",
        "profile_img_url": null
      },
      "created_at": "2024-06-10T09:00:00Z",
      "updated_at": "2024-06-15T14:30:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "size": 20,
  "filter_hash": "eyJzdGF0dXMiOiBbImFjdGl2ZSJdfQ=="
}

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

422 Unprocessable Entity

Cause: Invalid query parameter value (e.g. unrecognized status or direction)

{
  "detail": [
    {
      "loc": ["query", "transport_direction"],
      "msg": "value is not a valid enumeration member; permitted: 'downstream', 'upstream'",
      "type": "type_error.enum"
    }
  ]
}

Get Transport Route

Retrieve a single transport route by ID

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

​Request

​Headers

​Query Parameters

​Response

​Route Fields

​Section Fields

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Related Endpoints

Get Transport Route

Create Transport Route

Update Transport Route

Transport Overview

Request

Headers

Query Parameters

Response

Route Fields

Section Fields

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Related Endpoints