Skip to main content
GET
/
v1
/
transports
/
combinations
List Transport Combinations
const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/transports/combinations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "transport_type": "<string>",
  "travel_method": {},
  "refrigerated": true,
  "electric": true,
  "detail": {},
  "boundaries": {
    "from": {},
    "to": {},
    "unit": "<string>"
  },
  "reference_product": {}
}

​
List Transport Combinations

Returns every valid combination of transport_type, travel_method, refrigerated, electric, and detail that has a mapped emission factor in Dcycle. Use this endpoint to discover which combinations are accepted before creating or importing transport routes.
Always validate your transport sections against this list before submitting them. Sections with an invalid combination will be rejected with an INVALID_TRANSPORT_COMBINATION error.

​
Request

​
Headers

​
x-api-key
string
API key for authentication. Either this header or Authorization is required.Example: sk_live_1234567890abcdef
​
Authorization
string
Bearer token for authentication. Either this header or x-api-key is required.Example: Bearer sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUID.Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Query Parameters

All query parameters are optional and act as filters on the full combination list.
​
transport_type
string
Filter by transport mode.Accepted values: road, air, maritime, rail, do_not_knowUse do_not_know when the mode is unknown — Dcycle will infer it automatically from the origin/destination pair (road for same-country, road-reachable routes; air otherwise).
​
travel_method
string
Filter by the specific vehicle type within the transport mode.Accepted values: car, truck, motorbike, bicycle, electric_kick_scooterNot all transport types support every travel method. Call this endpoint without filters to see which transport_type + travel_method pairings are valid.
​
refrigerated
boolean
Filter to combinations that require (or do not require) refrigerated transport.
​
electric
boolean
Filter to combinations that use an electric vehicle.
​
detail
string
Filter by the detail sub-category used for distance- or weight-banded emission factors.Common values follow the patterns distance:ge:<km>, distance:lt:<km>, weight:ge:<kg>.

​
Response

Returns an array of TransportCombinationSch objects.
​
transport_type
string
Transport mode for this combination: road, air, maritime, rail, or do_not_know.
​
travel_method
string | null
Vehicle type within the mode (car, truck, motorbike, bicycle, electric_kick_scooter), or null when the mode does not distinguish by vehicle.
​
refrigerated
boolean
Whether this combination applies to refrigerated (temperature-controlled) transport.
​
electric
boolean
Whether this combination applies to electric vehicles.
​
detail
string | null
Sub-category selector used to pick the correct emission factor when distance or cargo weight affects the factor value. null when no sub-category is needed.Examples:
  • "distance:ge:4000" — air routes ≥ 4,000 km
  • "distance:ge:1500" — air routes ≥ 1,500 km and < 4,000 km
  • "weight:ge:32000" — road truck routes carrying > 32,000 kg
  • "weight:ge:3500" — road truck routes carrying ≤ 7,500 kg
​
boundaries
array | null
Distance or weight bands that define the applicability of this combination. Each entry describes one boundary condition.
​
reference_product
string | null
Internal name of the ecoinvent emission factor activity mapped to this combination. Useful for traceability and debugging emission factor lookups.Example: "transport, freight, lorry >32 metric ton, EURO6 {GLO}| transport, freight, lorry >32 metric ton, EURO6 | Cut-off, U"

​
Example

# List all combinations
curl "https://api.dcycle.io/v1/transports/combinations" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

# Filter to road truck combinations only
curl "https://api.dcycle.io/v1/transports/combinations?transport_type=road&travel_method=truck" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

# Filter to air, non-refrigerated combinations
curl "https://api.dcycle.io/v1/transports/combinations?transport_type=air&refrigerated=false" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

​
Successful Response

[
  {
    "transport_type": "road",
    "travel_method": "truck",
    "refrigerated": false,
    "electric": false,
    "detail": "weight:ge:32000",
    "boundaries": [
      { "from": 32000, "to": null, "unit": "kg" }
    ],
    "reference_product": "transport, freight, lorry >32 metric ton, EURO6 {GLO}| transport, freight, lorry >32 metric ton, EURO6 | Cut-off, U"
  },
  {
    "transport_type": "road",
    "travel_method": "truck",
    "refrigerated": false,
    "electric": false,
    "detail": "weight:ge:16000",
    "boundaries": [
      { "from": 16000, "to": 32000, "unit": "kg" }
    ],
    "reference_product": "transport, freight, lorry 16-32 metric ton, EURO6 {GLO}| transport, freight, lorry 16-32 metric ton, EURO6 | Cut-off, U"
  },
  {
    "transport_type": "air",
    "travel_method": null,
    "refrigerated": false,
    "electric": false,
    "detail": "distance:ge:4000",
    "boundaries": [
      { "from": 4000, "to": null, "unit": "km" }
    ],
    "reference_product": "transport, freight, aircraft, long haul {GLO}| transport, freight, aircraft, long haul | Cut-off, U"
  },
  {
    "transport_type": "maritime",
    "travel_method": null,
    "refrigerated": false,
    "electric": false,
    "detail": null,
    "boundaries": null,
    "reference_product": "transport, freight, sea, container ship {GLO}| transport, freight, sea, container ship | Cut-off, U"
  }
]

​
How detail Is Selected Automatically

When you create a transport route, Dcycle selects the correct detail value for you based on the route’s attributes:
Transport typeSelection logic
AirDistance bands: distance:lt:800, distance:ge:800, distance:ge:1500, distance:ge:4000
Road / TruckCargo weight bands: weight:ge:3500 (≤ 7,500 kg), weight:ge:7500, weight:ge:16000, weight:ge:32000
Other modesdetail is always null
You only need to specify detail explicitly in file uploads or direct API calls if you want to override this automatic selection.

​
Common Errors

​
401 Unauthorized

Cause: Missing or invalid API key / Bearer token. 
{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

​
422 Unprocessable Entity

Cause: An invalid value was passed for transport_type, travel_method, or another filter parameter. 
{
  "detail": [
    {
      "loc": ["query", "transport_type"],
      "msg": "value is not a valid enumeration member; permitted: 'road', 'air', 'maritime', 'rail', 'do_not_know'",
      "type": "type_error.enum"
    }
  ]
}

Transport Overview

Learn the full Transport API data model and workflow

Get Transport Route

Retrieve a single transport route with its sections and emissions

Upload Transport File

Bulk-create transport routes from a spreadsheet file

Presigned URL Upload

Upload large files directly to S3 via a presigned URL