Transport API

The Transport API lets you create and manage transport routes for tracking Scope 3 upstream and downstream transportation emissions. Each route can have multiple sections (legs) with different transport types, and emissions are automatically calculated using ecoinvent emission factors.

New API: These endpoints are part of the new API architecture and replace the legacy transport_routes and transport_sections endpoints.

Key Features

Multi-Section Routes: Define routes with multiple transport legs (e.g., truck to port, ship overseas, truck to warehouse)
Automatic Emissions Calculation: CO2e emissions calculated per section using ecoinvent factors
Automatic Distance Calculation: Distances computed via CERDI (maritime), Google Maps (road/rail), or haversine formula (air) — or provided manually
Bulk Operations: Upload routes via CSV/Excel or delete in bulk by IDs or filters
Presigned URL Uploads: Upload large files directly to S3 via presigned URLs
Version History: Track changes to transport routes over time
Flexible Filtering: Filter by date, status, direction, file, and CO2e calculation status

Authentication

All endpoints support both authentication methods:

API Key: Include in x-api-key header

Headers

All requests must include:

string

required

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

string

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

Available Endpoints

Transport Route Management

List Transport Routes

Retrieve all transport routes with filtering, sorting, and pagination

Get Transport Route

Get a specific transport route by ID with all sections and emissions

Create Transport Route

Create a new transport route with one or more sections

Update Transport Route

Modify a transport route and its sections

Delete Transport Route

Remove a transport route

Get Route Counts

Get aggregate counts by status (pending, active, error)

Bulk Operations

Upload File

Upload transport routes via CSV/Excel file

Presigned URL Upload

Get a presigned S3 URL for large file uploads

Bulk Delete by IDs

Delete up to 100,000 transport routes by ID

Bulk Delete by Filters

Delete all routes matching filter criteria

Reference Data

Transport Combinations

Get valid transport type/method combinations

Version History

View change history for a transport route

do_not_know Inference

How Dcycle infers transport mode and distance automatically

Data Model

Transport Route Object

A transport route represents a shipment with one or more transport sections (legs):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "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,
  "status": "active",
  "sections": [
    {
      "id": "section-uuid-001",
      "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",
      "emissions": [
        {"value": 12.34, "gas": "co2e", "unit_name": "kgCO2e"}
      ]
    },
    {
      "id": "section-uuid-002",
      "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",
      "emissions": [
        {"value": 233.33, "gas": "co2e", "unit_name": "kgCO2e"}
      ]
    }
  ],
  "file_id": null,
  "created_at": "2024-06-10T09:00:00Z",
  "updated_at": "2024-06-15T14:30:00Z"
}

Transport Route Attributes

Field	Type	Description
`id`	UUID	Unique identifier
`name`	string \| null	Optional route name
`transport_date`	date	Date of transport (YYYY-MM-DD)
`quantity_transported`	decimal	Amount transported (max 10 digits, 3 decimal places)
`supplier`	string \| null	Optional supplier name
`transport_direction`	string	`downstream` (outbound to customers) or `upstream` (inbound from suppliers)
`transport_frequency`	string \| null	Recurrence: `once`, `weekly`, `monthly`
`unit`	object	Measurement unit for quantity
`co2e`	float \| null	Calculated CO2-equivalent emissions in kg. `null` if no impacts calculated yet
`status`	string	Route status: `pending`, `active`, `error`
`sections`	array	List of transport sections (legs)
`file_id`	UUID \| null	ID of the uploaded file (if bulk-uploaded)
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp

Transport Section Attributes

Field	Type	Description
`id`	UUID	Section identifier
`part`	integer	Sequence number within the route (1-based)
`transport_type`	string	See Transport Types
`travel_method`	string \| null	Sub-type for road: `car`, `truck`, `motorbike`, `bicycle`, `electric_kick_scooter`
`electric`	boolean	Whether the vehicle is electric
`refrigerated`	boolean	Whether the cargo is refrigerated
`detail`	string \| null	Additional detail category (used for emission factor selection)
`origin`	string	Origin location address
`destination`	string	Destination location address
`kms`	float \| null	Calculated distance in kilometers
`kms_manual`	float \| null	User-provided distance override (max 7 digits, 2 decimal places)
`distance_manual`	boolean	`true` when `kms_manual` was used instead of auto-calculation
`kms_source`	string \| null	Method used to calculate distance. See Distance Calculation Methods
`status`	string	Section status: `pending`, `active`, `error`
`step`	string \| null	Current processing step: `geocoding`, `impact_calculation`, `completed`
`error_messages`	array \| null	List of error messages if `status` is `error`
`emissions`	array \| null	CO2e emissions per gas: `[{"value": 12.34, "gas": "co2e", "unit_name": "kgCO2e"}]`

Transport Types

Value	Description
`road`	Road freight transport (truck, car, etc.)
`air`	Air freight
`maritime`	Sea freight (container ship, tanker, etc.)
`rail`	Rail freight
`do_not_know`	Unknown transport type — system infers road, maritime, or air based on origin/destination countries

Distance Calculation Methods

The kms_source field on each section tells you how the distance was determined:

Value	Description
`cerdi_sea_distance`	Maritime, different countries — CERDI country-pair formula: port-to-port sea distance + capital-to-port land legs
`searoute_sea_distance`	Maritime, same country — navigable-water graph (e.g. mainland Spain → Canary Islands)
`haversine_sea_distance`	Maritime, same country — haversine fallback when searoute is unavailable
`haversine_formula`	Air transport — great-circle distance between geocoded points
`google_maps_distance_matrix_v1`	Road or rail — Google Maps Distance Matrix API
`aws_location_route_matrix`	Road or rail — AWS Location Service (alternative to Google Maps)
`default`	Same-country maritime (500 km hardcoded) or same-place road (3 km hardcoded)
`manual`	Distance provided directly by the user via `kms_manual`
`null`	Not available — section was created before geocoding was introduced, or geocoding failed

CERDI distance explained: For maritime routes between different countries, the distance is calculated as the sum of three components from the CERDI dataset: the sea route between the countries’ main ports, the land distance from the origin country’s capital to its main port, and the land distance from the destination country’s capital to its main port. This is a country-level approximation — all shipments between two countries receive the same maritime distance regardless of the specific origin/destination city.

Error Handling

Common HTTP Status Codes

Status	Meaning	Solution
200	Success	—
201	Created	—
204	No Content (delete successful)	—
400	Bad Request	Check request parameters and format
401	Unauthorized	Verify API key or JWT token
403	Forbidden	Verify the user has access to the organization
404	Not Found	Check resource ID or organization
422	Validation Error	Review error details in response
500	Server Error	Contact support if persists

Common Use Cases

Create a multi-leg shipment

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 Berlin via Paris",
    "transport_date": "2024-06-15",
    "quantity_transported": 1500,
    "transport_direction": "downstream",
    "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
    "sections": [
      {
        "transport_type": "road",
        "travel_method": "truck",
        "origin": "Madrid, Spain",
        "destination": "Paris, France",
        "electric": false,
        "refrigerated": false
      },
      {
        "transport_type": "rail",
        "origin": "Paris, France",
        "destination": "Berlin, Germany",
        "electric": true,
        "refrigerated": false
      }
    ]
  }'

import requests
import os

response = requests.post(
    "https://api.dcycle.io/v1/transports",
    headers={
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    },
    json={
        "name": "Madrid to Berlin via Paris",
        "transport_date": "2024-06-15",
        "quantity_transported": 1500,
        "transport_direction": "downstream",
        "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
        "sections": [
            {
                "transport_type": "road",
                "travel_method": "truck",
                "origin": "Madrid, Spain",
                "destination": "Paris, France",
                "electric": False,
                "refrigerated": False,
            },
            {
                "transport_type": "rail",
                "origin": "Paris, France",
                "destination": "Berlin, Germany",
                "electric": True,
                "refrigerated": False,
            },
        ],
    },
)

transport = response.json()
print(f"Route created: {transport['id']}, CO2e: {transport['co2e']} kgCO2e")

Upload transport data via presigned URL

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}

# Step 1: Get presigned URL
presigned = requests.post(
    "https://api.dcycle.io/v1/transports/upload/presigned-url",
    headers=headers,
    json={
        "file_name": "transport_data_q2.xlsx",
        "transport_direction": "downstream",
    },
).json()

# Step 2: Upload file directly to S3
with open("transport_data_q2.xlsx", "rb") as f:
    requests.put(presigned["upload_url"], data=f)

print(f"File uploaded. File ID: {presigned['file_id']}")

Logistics API

Manage logistics operations (GLEC Framework)

Vehicles API

Manage fleet vehicles and fuel consumption

GHG Protocol Scope 3

Scope 3 upstream/downstream transport guide

ISO 14064 Category 3

ISO 14064 transportation emissions guide

MCP Tools

Query transport records from AI assistants via MCP

Get Waste Water Treatment by ID Transport Type Inference (do_not_know)

​Transport API

​Key Features

​Authentication

​Headers

​Available Endpoints

​Transport Route Management

List Transport Routes

Get Transport Route

Create Transport Route

Update Transport Route

Delete Transport Route

Get Route Counts

​Bulk Operations

Upload File

Presigned URL Upload

Bulk Delete by IDs

Bulk Delete by Filters

​Reference Data

Transport Combinations

Version History

do_not_know Inference

​Data Model

​Transport Route Object

​Transport Route Attributes

​Transport Section Attributes

​Transport Types

​Distance Calculation Methods

​Error Handling

​Common HTTP Status Codes

​Common Use Cases

​Create a multi-leg shipment

​Upload transport data via presigned URL

​Related Documentation

Logistics API

Vehicles API

GHG Protocol Scope 3

ISO 14064 Category 3

MCP Tools

Transport API

Key Features

Authentication

Headers

Available Endpoints

Transport Route Management

Bulk Operations

Reference Data

Data Model

Transport Route Object

Transport Route Attributes

Transport Section Attributes

Transport Types

Distance Calculation Methods

Error Handling

Common HTTP Status Codes

Common Use Cases

Create a multi-leg shipment

Upload transport data via presigned URL

Related Documentation