Skip to main content

​
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
  • 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 require authentication using either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests must include:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
x-api-key
string
required
Your API key for authenticationExample: 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

​
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 Berlin Shipment",
  "transport_date": "2024-06-15",
  "quantity_transported": 1500.0,
  "supplier": "LogiTrans GmbH",
  "transport_direction": "outbound",
  "transport_frequency": null,
  "unit": {
    "id": "unit-uuid",
    "name": "kilogram",
    "symbol": "kg"
  },
  "co2e": 245.67,
  "status": "active",
  "sections": [
    {
      "id": "section-uuid-001",
      "part": 1,
      "transport_type": "truck",
      "travel_method": null,
      "electric": false,
      "refrigerated": false,
      "origin": "Madrid, Spain",
      "destination": "Paris, France",
      "kms": 1275.0,
      "status": "active",
      "emissions": [...]
    },
    {
      "id": "section-uuid-002",
      "part": 2,
      "transport_type": "rail",
      "travel_method": null,
      "electric": true,
      "refrigerated": false,
      "origin": "Paris, France",
      "destination": "Berlin, Germany",
      "kms": 1050.0,
      "status": "active",
      "emissions": [...]
    }
  ],
  "file_id": null,
  "created_at": "2024-06-10T09:00:00Z",
  "updated_at": "2024-06-15T14:30:00Z"
}

​
Transport Route Attributes

FieldTypeDescription
idUUIDUnique identifier
namestringOptional route name
transport_datedateDate of transport (YYYY-MM-DD)
quantity_transporteddecimalAmount transported (max 10 digits, 3 decimal places)
supplierstringOptional supplier name
transport_directionstringoutbound or inbound
transport_frequencystringRecurrence: daily, weekly, monthly, etc.
unitobjectMeasurement unit for quantity
co2efloatCalculated CO2-equivalent emissions
statusstringRoute status: pending, active, error
sectionsarrayList of transport sections (legs)
file_idUUIDID of the uploaded file (if bulk-uploaded)
created_atdatetimeCreation timestamp
updated_atdatetimeLast update timestamp

​
Transport Section Attributes

FieldTypeDescription
idUUIDSection identifier
partintegerSequence number within the route
transport_typestringtruck, air, maritime, rail, car, motorbike, bicycle, electric_kick_scooter, do_not_know
travel_methodstringTravel method (type-specific)
electricbooleanWhether the vehicle is electric
refrigeratedbooleanWhether the cargo is refrigerated
detailstringAdditional detail category
originstringOrigin location
destinationstringDestination location
kmsfloatDistance in kilometers
statusstringSection calculation status

​
Transport Types

TypeDescription
truckRoad freight transport
airAir freight
maritimeSea freight
railRail freight
carCar transport
motorbikeMotorbike transport
bicycleBicycle transport
electric_kick_scooterElectric scooter
do_not_knowUnknown transport type (uses default factors)

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success-
201Created-
204No Content (delete successful)-
400Bad RequestCheck request parameters and format
401UnauthorizedVerify API key
404Not FoundCheck resource ID or organization
422Validation ErrorReview error details in response
500Server ErrorContact support if persists

​
Common Use Cases

​
Create a multi-leg shipment

import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-organization-id": "YOUR_ORG_ID"
}

transport = requests.post(
    "https://api.dcycle.io/v2/transports",
    headers=headers,
    json={
        "name": "Madrid to Berlin via Paris",
        "transport_date": "2024-06-15",
        "quantity_transported": 1500,
        "transport_direction": "outbound",
        "unit_id": "unit-uuid-for-kg",
        "sections": [
            {
                "transport_type": "truck",
                "origin": "Madrid, Spain",
                "destination": "Paris, France",
                "electric": False,
                "refrigerated": False
            },
            {
                "transport_type": "rail",
                "origin": "Paris, France",
                "destination": "Berlin, Germany",
                "electric": True,
                "refrigerated": False
            }
        ]
    }
).json()

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

​
Upload transport data via presigned URL

import requests

# Step 1: Get presigned URL
presigned = requests.post(
    "https://api.dcycle.io/v2/transports/upload/presigned-url",
    headers=headers,
    json={
        "file_name": "transport_data_q2.xlsx",
        "transport_direction": "outbound"
    }
).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']}")

​
Bulk delete routes from a specific file upload

# Delete all routes that were uploaded from a specific file
response = requests.post(
    "https://api.dcycle.io/v2/transports/bulk-delete-by-filters",
    headers=headers,
    params={"file_id": "file-uuid-to-delete"}
)

result = response.json()
print(f"Deleted {result['deleted_count']} routes")

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