List Transport Routes

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

{
  "items": [
    {}
  ],
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "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[].destination": "<string>",
  "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[].emissions": {}
}

GET

transports

List Transport Routes

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

{
  "items": [
    {}
  ],
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "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[].destination": "<string>",
  "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[].emissions": {}
}

List Transport Routes

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

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

Query Parameters

string

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

from_date

date

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

to_date

date

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

status

array of string

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

transport_direction

string

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

file_id

array of UUID

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

created_at_from

datetime

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

created_at_to

datetime

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

co2e_status

string

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

sort

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)

page

integer

default:"1"

Page number (1-based)

size

integer

default:"50"

Number of results per page

Response

items

array

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

total

integer

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

page

integer

Current page number

size

integer

Number of items per page

filter_hash

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.

Route Fields

items[].id

string

Unique identifier (UUID)

items[].name

string | null

Optional route name

items[].transport_date

date | null

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

items[].quantity_transported

number

Amount transported (max 10 digits, 3 decimal places)

items[].supplier

string | null

Optional supplier name

items[].transport_direction

string

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

items[].transport_frequency

string | null

Recurrence: once, weekly, monthly

items[].unit

object

Measurement unit for the quantity transported

Show unit fields

items[].unit.id

string

UUID of the unit

items[].unit.name

string

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

items[].unit.type

string

Unit type, e.g. solid, liquid

items[].co2e

number | null

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

items[].emissions

array

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

items[].status

string

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

items[].file_id

string | null

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

items[].file_name

string | null

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

items[].sections

array

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

items[].uploaded_by

object | null

User who uploaded this route

Show uploaded_by fields

items[].uploaded_by.id

string

User ID

items[].uploaded_by.first_name

string | null

First name

items[].uploaded_by.last_name

string | null

Last name

items[].uploaded_by.profile_img_url

string | null

Profile image URL

items[].created_at

datetime

ISO 8601 creation timestamp

items[].updated_at

datetime

ISO 8601 last-update timestamp

Section Fields

items[].sections[].id

string

Section UUID

items[].sections[].part

integer

Sequence number within the route (1-based)

items[].sections[].transport_type

string

road, air, maritime, rail, or do_not_know

items[].sections[].travel_method

string | null

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

items[].sections[].electric

boolean

Whether the vehicle is electric

items[].sections[].refrigerated

boolean

Whether the cargo is refrigerated

items[].sections[].detail

string | null

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

items[].sections[].origin

string

Origin location address

items[].sections[].destination

string

Destination location address

items[].sections[].kms

number | null

Calculated or user-provided distance in kilometers

items[].sections[].kms_manual

number | null

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

items[].sections[].distance_manual

boolean

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

items[].sections[].kms_source

string | null

Method used to compute the distance. See the Transport Overview for all values.

items[].sections[].status

string

Section status: pending, active, error

items[].sections[].step

string | null

Current processing step: geocoding, impact_calculation, completed

items[].sections[].error_messages

array | null

List of error messages when status is error

items[].sections[].emissions

array | null

CO2e emissions for this section: [{"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}"

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

Get Transport Route Create Transport Route

​List Transport Routes

​Request

​Authentication

​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

List Transport Routes

Request

Authentication

Headers

Query Parameters

Response

Route Fields

Section Fields

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Related Endpoints