Create Transport Route

const options = {
  method: 'POST',
  headers: {'x-organization-id': '<x-organization-id>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    name: '<string>',
    transport_date: '<string>',
    quantity_transported: 123,
    supplier: '<string>',
    transport_direction: '<string>',
    unit_id: '<string>',
    sections: [
      {
        'sections[].transport_type': '<string>',
        'sections[].travel_method': '<string>',
        'sections[].electric': true,
        'sections[].refrigerated': true,
        'sections[].detail': '<string>',
        'sections[].origin': '<string>',
        'sections[].destination': '<string>',
        'sections[].kms_manual': 123
      }
    ]
  })
};

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

{
  "id": "<string>",
  "name": {},
  "transport_date": {},
  "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": [
    {}
  ],
  "uploaded_by": {},
  "created_at": {},
  "updated_at": {}
}

POST

transports

Create Transport Route

const options = {
  method: 'POST',
  headers: {'x-organization-id': '<x-organization-id>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    name: '<string>',
    transport_date: '<string>',
    quantity_transported: 123,
    supplier: '<string>',
    transport_direction: '<string>',
    unit_id: '<string>',
    sections: [
      {
        'sections[].transport_type': '<string>',
        'sections[].travel_method': '<string>',
        'sections[].electric': true,
        'sections[].refrigerated': true,
        'sections[].detail': '<string>',
        'sections[].origin': '<string>',
        'sections[].destination': '<string>',
        'sections[].kms_manual': 123
      }
    ]
  })
};

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

{
  "id": "<string>",
  "name": {},
  "transport_date": {},
  "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": [
    {}
  ],
  "uploaded_by": {},
  "created_at": {},
  "updated_at": {}
}

Create Transport Route

Create a new transport route for your organization. A route consists of one or more sections (legs), each describing a segment of the journey with its own transport mode and distance. Distances are geocoded automatically from origin/destination addresses, or you can override them with kms_manual. After creation the route is in status: pending. Emissions are calculated asynchronously — poll GET /v1/transports/ until status becomes active or error.

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

Content-Type

string

required

Must be application/json

Body

name

string

Optional human-readable label for this route (e.g. "Barcelona → Damascus Q2")

transport_date

date

required

Date of the transport event (YYYY-MM-DD)Example: "2024-06-15"

quantity_transported

decimal

required

Amount of cargo transported. Must be greater than 0, max 10 digits with 3 decimal places.Example: 1500.000

supplier

string

Optional supplier or carrier name

transport_direction

string

required

Direction of the transport:

downstream — outbound, goods sent to customers
upstream — inbound, goods received from suppliers

unit_id

UUID

required

UUID of the unit of measurement for quantity_transported. Common values:

Unit	UUID
kilogram (kg)	`61743a63-ff70-459c-9567-5eee8f7dfd5c`
metric tonne (t)	`cab66828-c2b1-431b-92af-f9ab37149d3c`

sections

array

required

Ordered list of transport legs. At least one section is required. Sections are processed in order and assigned part numbers starting from 1.

Show section fields

sections[].transport_type

string

required

Mode of transport for this leg:

road — truck, car, or other road vehicle
air — air freight
maritime — sea freight
rail — train
do_not_know — let Dcycle infer the best mode from the origin/destination pair

sections[].travel_method

string

Road sub-type (only relevant when transport_type is road): car, truck, motorbike, bicycle, electric_kick_scooter

sections[].electric

boolean

required

Whether the vehicle is electrically powered. Set to false when unknown.

sections[].refrigerated

boolean

required

Whether the cargo requires refrigeration. Set to false when unknown.

sections[].detail

string

Additional detail used for emission factor selection, such as a distance band or weight class (e.g. ship_container, large_hgv). Leave unset to use the default factor for the transport type.

sections[].origin

string

Origin address for this leg (e.g. "Madrid, Spain"). Dcycle geocodes this address and computes the distance to the destination automatically. Required if kms_manual is not provided.

sections[].destination

string

Destination address for this leg (e.g. "Barcelona Port, Spain"). Required if kms_manual is not provided.

sections[].kms_manual

decimal

Distance override in kilometers. Use this to bypass geocoding entirely. Must be greater than 0, max 7 digits with 2 decimal places.Example: 4626.00

Response

Returns the newly created TransportRouteSch object with HTTP status 201 Created.

Emissions are calculated asynchronously. Immediately after creation, status will be pending and co2e will be null. Poll GET /v1/transports/ until status is active (success) or error (calculation failed). Typical calculation time is a few seconds per section.

string

Unique identifier (UUID) of the new route

name

string | null

Route name as provided

transport_date

date | null

Date of transport (YYYY-MM-DD)

quantity_transported

number

Amount transported

supplier

string | null

Supplier name as provided

transport_direction

string

downstream or upstream

transport_frequency

string | null

Recurrence value set by the system: once, weekly, monthly

unit

object

Resolved unit of measurement

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. null immediately after creation — available once status is active.

emissions

array

Route-level emissions summary. Empty until calculation completes.

status

string

pending immediately after creation. Transitions to active when calculation succeeds, or error if it fails.

file_id

string | null

Always null for routes created via this endpoint (only set for bulk-uploaded routes)

sections

array

Created sections with their assigned part numbers and initial geocoding state. See Get Transport Route for the full section schema.

uploaded_by

object | null

The authenticated user who created this route

created_at

datetime

ISO 8601 creation timestamp

updated_at

datetime

ISO 8601 last-update timestamp

Example

curl -X POST "https://api.dcycle.io/v1/transports" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Madrid to Syria Shipment",
    "transport_date": "2024-06-15",
    "quantity_transported": 1500.000,
    "supplier": "LogiTrans S.A.",
    "transport_direction": "downstream",
    "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
    "sections": [
      {
        "transport_type": "road",
        "travel_method": "truck",
        "electric": false,
        "refrigerated": false,
        "origin": "Madrid, Spain",
        "destination": "Barcelona Port, Spain"
      },
      {
        "transport_type": "maritime",
        "electric": false,
        "refrigerated": false,
        "detail": "ship_container",
        "origin": "Barcelona Port, Spain",
        "destination": "Latakia Port, Syria"
      }
    ]
  }'

Successful Response (201 Created)

{
  "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": null,
  "emissions": [],
  "status": "pending",
  "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": null,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": null,
      "status": "pending",
      "step": "geocoding",
      "error_messages": null,
      "emissions": null,
      "created_at": "2024-06-10T09:00:00Z",
      "updated_at": "2024-06-10T09:00: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": null,
      "kms_manual": null,
      "distance_manual": false,
      "kms_source": null,
      "status": "pending",
      "step": "geocoding",
      "error_messages": null,
      "emissions": null,
      "created_at": "2024-06-10T09:00:00Z",
      "updated_at": "2024-06-10T09:00: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-10T09:00: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: The provided unit_id does not exist

{"detail": "Unit not found", "code": "UNIT_NOT_FOUND"}

422 Unprocessable Entity

Cause: Missing required field or invalid value

{
  "detail": [
    {
      "loc": ["body", "transport_direction"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Cause: sections array is empty

{
  "detail": [
    {
      "loc": ["body", "sections"],
      "msg": "ensure this value has at least 1 items",
      "type": "value_error.list.min_items"
    }
  ]
}

Get Transport Route

Retrieve a single route by ID (use this to poll for calculated emissions)

List Transport Routes

Retrieve all transport routes with filtering and pagination

Update Transport Route

Modify a transport route and its sections

Transport Overview

Full data model and distance calculation reference

List Transport Routes Update Transport Route

​Create Transport Route

​Request

​Authentication

​Headers

​Body

​Response

​Example

​Successful Response (201 Created)

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​Related Endpoints

Get Transport Route

List Transport Routes

Update Transport Route

Transport Overview

Create Transport Route

Request

Authentication

Headers

Body

Response

Example

Successful Response (201 Created)

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

Related Endpoints