Create Logistics Request

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    origin: '<string>',
    destination: '<string>',
    distance_km: 123,
    load: 123,
    load_unit: '<string>',
    load_factor: 123,
    toc: '<string>',
    category: '<string>',
    origin_country: '<string>',
    year: 123,
    cleaning: true,
    movement_id: '<string>',
    client: '<string>',
    shipment_date: '<string>',
    movement_stretch: '<string>',
    movement_stage: '<string>',
    vehicle_license_plate: '<string>',
    trailer_license_plate: '<string>',
    subcontractor: true,
    tkm: 123,
    hub_id: '<string>',
    package_key: '<string>'
  })
};

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

import requests

url = "https://api.dcycle.io/v1/logistics/requests"

payload = {
    "origin": "<string>",
    "destination": "<string>",
    "distance_km": 123,
    "load": 123,
    "load_unit": "<string>",
    "load_factor": 123,
    "toc": "<string>",
    "category": "<string>",
    "origin_country": "<string>",
    "year": 123,
    "cleaning": True,
    "movement_id": "<string>",
    "client": "<string>",
    "shipment_date": "<string>",
    "movement_stretch": "<string>",
    "movement_stage": "<string>",
    "vehicle_license_plate": "<string>",
    "trailer_license_plate": "<string>",
    "subcontractor": True,
    "tkm": 123,
    "hub_id": "<string>",
    "package_key": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/logistics/requests \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "origin": "<string>",
  "destination": "<string>",
  "distance_km": 123,
  "load": 123,
  "load_unit": "<string>",
  "load_factor": 123,
  "toc": "<string>",
  "category": "<string>",
  "origin_country": "<string>",
  "year": 123,
  "cleaning": true,
  "movement_id": "<string>",
  "client": "<string>",
  "shipment_date": "<string>",
  "movement_stretch": "<string>",
  "movement_stage": "<string>",
  "vehicle_license_plate": "<string>",
  "trailer_license_plate": "<string>",
  "subcontractor": true,
  "tkm": 123,
  "hub_id": "<string>",
  "package_key": "<string>"
}
'

{
  "id": "<string>",
  "co2e": 123,
  "created_at": {},
  "updated_at": {},
  "origin": "<string>",
  "destination": "<string>",
  "distance_km": 123,
  "load": 123,
  "load_unit": "<string>",
  "category": "<string>",
  "toc": "<string>",
  "origin_country": "<string>",
  "year": 123,
  "movement_id": "<string>",
  "client": "<string>",
  "shipment_date": "<string>",
  "movement_stretch": "<string>",
  "movement_stage": "<string>",
  "vehicle_license_plate": "<string>",
  "trailer_license_plate": "<string>",
  "subcontractor": true,
  "tkm": 123,
  "hub_id": "<string>",
  "package_id": "<string>",
  "package_key": "<string>"
}

POST

logistics

requests

Create Logistics Request

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    origin: '<string>',
    destination: '<string>',
    distance_km: 123,
    load: 123,
    load_unit: '<string>',
    load_factor: 123,
    toc: '<string>',
    category: '<string>',
    origin_country: '<string>',
    year: 123,
    cleaning: true,
    movement_id: '<string>',
    client: '<string>',
    shipment_date: '<string>',
    movement_stretch: '<string>',
    movement_stage: '<string>',
    vehicle_license_plate: '<string>',
    trailer_license_plate: '<string>',
    subcontractor: true,
    tkm: 123,
    hub_id: '<string>',
    package_key: '<string>'
  })
};

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

import requests

url = "https://api.dcycle.io/v1/logistics/requests"

payload = {
    "origin": "<string>",
    "destination": "<string>",
    "distance_km": 123,
    "load": 123,
    "load_unit": "<string>",
    "load_factor": 123,
    "toc": "<string>",
    "category": "<string>",
    "origin_country": "<string>",
    "year": 123,
    "cleaning": True,
    "movement_id": "<string>",
    "client": "<string>",
    "shipment_date": "<string>",
    "movement_stretch": "<string>",
    "movement_stage": "<string>",
    "vehicle_license_plate": "<string>",
    "trailer_license_plate": "<string>",
    "subcontractor": True,
    "tkm": 123,
    "hub_id": "<string>",
    "package_key": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/logistics/requests \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "origin": "<string>",
  "destination": "<string>",
  "distance_km": 123,
  "load": 123,
  "load_unit": "<string>",
  "load_factor": 123,
  "toc": "<string>",
  "category": "<string>",
  "origin_country": "<string>",
  "year": 123,
  "cleaning": true,
  "movement_id": "<string>",
  "client": "<string>",
  "shipment_date": "<string>",
  "movement_stretch": "<string>",
  "movement_stage": "<string>",
  "vehicle_license_plate": "<string>",
  "trailer_license_plate": "<string>",
  "subcontractor": true,
  "tkm": 123,
  "hub_id": "<string>",
  "package_key": "<string>"
}
'

{
  "id": "<string>",
  "co2e": 123,
  "created_at": {},
  "updated_at": {},
  "origin": "<string>",
  "destination": "<string>",
  "distance_km": 123,
  "load": 123,
  "load_unit": "<string>",
  "category": "<string>",
  "toc": "<string>",
  "origin_country": "<string>",
  "year": 123,
  "movement_id": "<string>",
  "client": "<string>",
  "shipment_date": "<string>",
  "movement_stretch": "<string>",
  "movement_stage": "<string>",
  "vehicle_license_plate": "<string>",
  "trailer_license_plate": "<string>",
  "subcontractor": true,
  "tkm": 123,
  "hub_id": "<string>",
  "package_id": "<string>",
  "package_key": "<string>"
}

Create Logistics Request

Calculate CO2 equivalent (CO2e) emissions for a freight shipment with flexible parameters for origin/destination or direct distance input.

New API: This endpoint is part of the new API architecture with improved design and maintainability.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Body Parameters

string

Origin location of the shipment. Can be either:

Address string: City and country (e.g., "Madrid, Spain")
Hub Name: Name of a logistics hub registered in your organization

When a hub name is provided, the system automatically resolves it to the hub’s registered address. Required if distance_km is not provided.Examples:

Address: "Madrid, Spain"
Hub Name: "Madrid Distribution Center"

string

Destination location of the shipment. Can be either:

Address string: City and country (e.g., "Barcelona, Spain")
Hub Name: Name of a logistics hub registered in your organization

When a hub name is provided, the system automatically resolves it to the hub’s registered address. Required if distance_km is not provided.Examples:

Address: "Barcelona, Spain"
Hub Name: "Barcelona Warehouse"

Hub Name Resolution: When you provide a hub name as origin or destination, the system will:

Look up the hub by name in your organization’s registered hubs
Validate that the hub is active and belongs to your organization
Use the hub’s registered address for distance calculation

This is useful when you have predefined warehouse or distribution center locations. If the provided value does not match any hub name in your organization, it will be treated as a literal address string.

number

Distance in kilometers between origin and destination. If provided, takes priority over origin and destination.Example: 500

number

Load of the shipment. If not provided, it will be calculated from the TOC or category.Example: 1000

string

Unit of the load.Available values: kg, ton, pallets, teu, feuDefault: kg

number

Factor to divide the load by (between 0 and 1). Example: 100 pallets with 0.5 factor is 50 pallets.Default: 1.0

string

Type of vehicle to use for calculation. If omitted, it will be estimated from the category provided.Example: "van_diesel"

string

Category of the vehicle. Required if toc is not provided.Available values: road, rail, maritime, airExample: "road"

string

Country ISO 3166-1 alpha-2 code of the origin to use the region’s emission factors. If not provided, global factors will be used.Default: GLOExample: ES

integer

Year of the emission factor to use. If not provided, current year will be used.Example: 2024

boolean

If cleaning has been done, it will increase the emissions.Default: false

Traceability Parameters

These optional parameters allow you to track shipments with full traceability for logistics providers.

string

Unique identifier for the shipment movement, used for tracking and deduplication.Example: "MOV-2024-001234"

string

Client or customer identifier for the shipment.Example: "CORREOS-EXPRESS"

date

Date of the shipment (ISO 8601 format). If not provided, current date will be used.Example: "2024-11-25"

string

Stretch or segment of the movement (e.g., first mile, last mile).Example: "last_mile"

string

Stage of the movement in the logistics chain.Example: "delivery"

string

License plate of the vehicle used for the shipment.Example: "1234-ABC"

string

License plate of the trailer, if applicable.Example: "5678-XYZ"

boolean

Whether the shipment is handled by a subcontractor.Default: true

number

Tonne-kilometers (load in tonnes multiplied by distance in km). If provided, used directly for calculations instead of computing from load and distance.Example: 500.0

string

Identifier of the logistics hub associated with this shipment. This parameter serves two main purposes:

Emissions allocation: Identifies that a specific load for a client was stored in a hub, allowing the system to assign the corresponding hub storage emissions.
Origin substitution: When the hub address is registered in the system, it will be automatically used as the origin point for the leg, replacing the specified origin.

Example: "HUB-MAD-001"

Hub Integration: When you provide a hub_id, the system automatically handles two things: it attributes the appropriate storage emissions from that hub to your shipment, and if the hub has a registered address, it overrides the leg’s origin with the hub’s location. This ensures accurate emission tracking for warehouse and cross-docking operations.

Package Parameters (Multi-leg Shipments)

These parameters enable tracking of packages that travel through multiple legs.

string

Unique identifier for the package. When provided, this leg will be associated with the package. Requires movement_id to group packages into shipments.Example: "26830007899150601093463"

Package Tracking: When you provide package_key, the system automatically creates or finds the package and associates this leg with it. Multiple legs with the same package_key will be grouped together, and the package’s total distance and emissions will be aggregated.

Response

string

Unique identifier for the logistics request

number

Total CO2 equivalent emissions in kilograms

datetime

Timestamp when the request was created

datetime | null

Timestamp when the request was last updated

string

Shipment origin address. If a hub name was provided in the request, this will contain the resolved hub address.

string

Shipment destination address. If a hub name was provided in the request, this will contain the resolved hub address.

number

Distance in kilometers (if provided or calculated)

number

Transported load

string

Load unit of measurement

string

Vehicle category used

string

Type of vehicle (if provided)

string

Origin country code

integer

Year used for emission factors

string

Unique identifier for the shipment movement

string

Client or customer identifier

date

Date of the shipment

string

Stretch or segment of the movement

string

Stage of the movement in the logistics chain

string

License plate of the vehicle

string

License plate of the trailer

boolean

Whether handled by a subcontractor

number

Tonne-kilometers calculated or provided

string

Logistics hub identifier

string

UUID of the associated package (if package_key was provided)

string

Package identifier (if provided in request)

Example

curl -X POST "https://api.dcycle.io/v1/logistics/requests" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "Madrid, Spain",
    "destination": "Barcelona, Spain",
    "load": 1000,
    "load_unit": "kg",
    "category": "road"
  }'

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id,
    "Content-Type": "application/json"
}

payload = {
    "origin": "Madrid, Spain",
    "destination": "Barcelona, Spain",
    "load": 1000,
    "load_unit": "kg",
    "category": "road"
}

response = requests.post(
    "https://api.dcycle.io/v1/logistics/requests",
    headers=headers,
    json=payload
)

result = response.json()
print(f"Request ID: {result['id']}")
print(f"CO2e: {result['co2e']} kg")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId,
  'Content-Type': 'application/json'
};

const payload = {
  origin: "Madrid, Spain",
  destination: "Barcelona, Spain",
  load: 1000,
  load_unit: "kg",
  category: "road"
};

axios.post(
  'https://api.dcycle.io/v1/logistics/requests',
  payload,
  { headers }
)
.then(response => {
  console.log(`Request ID: ${response.data.id}`);
  console.log(`CO2e: ${response.data.co2e} kg`);
})
.catch(error => console.error(error));

Successful Response

{
  "id": "0b08bffd-a1e3-48cb-a477-aefa59131934",
  "origin": "CALLE MAESTRO FALLA 11, SALAMANCA, 37003",
  "destination": "C/ MONTERA, 25-27 - P.I. LOS VILLARES, VILLARES DE LA REINA, 37184",
  "origin_country": "ES",
  "distance_km": 3.4447,
  "load": 1.0,
  "load_unit": "kg",
  "load_factor": 1.0,
  "toc": "generic_average_road",
  "category": "road",
  "year": 2025,
  "cleaning": false,
  "co2e": 0.000528,
  "tkm": 0.00344,
  "movement_id": "9883000788469370",
  "client": "AMAZON",
  "shipment_date": "2025-05-19",
  "movement_stretch": "RECOGIDA",
  "movement_stage": "FIRST_MILE",
  "package_key": "98830007884693701030068",
  "package_id": "128be1de-9aa0-4c7d-891f-5daf5467107e",
  "subcontractor": false,
  "vehicle_license_plate": null,
  "trailer_license_plate": null,
  "hub_id": null,
  "created_at": "2025-12-04T06:42:35.973485",
  "updated_at": "2025-12-04T06:42:35.973489"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active. Get a new one from Settings → API.

404 Not Found

Cause: Organization not found

{
  "code": "ORGANIZATION_NOT_FOUND",
  "detail": "Organization with id=UUID('...') not found"
}

Solution: Verify that the x-organization-id header contains a valid organization UUID.

422 Validation Error

Cause: Missing required parameters or invalid values

{
  "detail": [
    {
      "loc": ["body", "category"],
      "msg": "Please provide a category if toc is not present",
      "type": "value_error"
    }
  ]
}

Solution: Ensure that either toc or category is provided. If using addresses, provide both origin and destination, or use distance_km instead.

404 Hub Not Found

Cause: A hub name was provided as origin/destination, but the hub is not active or doesn’t belong to your organization

{
  "code": "NOT_FOUND",
  "detail": "Origin hub not found"
}

Solution: Verify that:

The hub name is correct and exists in your organization
The hub status is active (not inactive, error, or archived)

400 Hub Has No Address

Cause: A hub name was provided as origin/destination, but the hub doesn’t have an address configured

{
  "code": "BAD_REQUEST",
  "detail": "Origin hub has no address configured"
}

Solution: Configure an address for the hub in your organization settings before using it as origin/destination.

Use Cases

Calculate Emissions with Addresses

Most common use case - let the API calculate distance from addresses:

def calculate_shipment_emissions(origin, destination, load_kg):
    """Calculate emissions for a shipment between two locations"""
    response = requests.post(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        json={
            "origin": origin,
            "destination": destination,
            "load": load_kg,
            "load_unit": "kg",
            "category": "road"
        }
    )

    result = response.json()
    return {
        "co2e": result["co2e"],
        "distance": result.get("distance_km")
    }

# Example usage
emissions = calculate_shipment_emissions(
    origin="Madrid, Spain",
    destination="Barcelona, Spain",
    load_kg=1500
)
print(f"Emissions: {emissions['co2e']} kg CO2e")

Using Hub Names for Origin/Destination

If you have logistics hubs registered in your organization, you can use their names instead of addresses:

def calculate_hub_to_hub_emissions(origin_hub_name, destination_hub_name, load_kg):
    """Calculate emissions between two logistics hubs"""
    response = requests.post(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        json={
            "origin": origin_hub_name,        # Hub name
            "destination": destination_hub_name,  # Hub name
            "load": load_kg,
            "load_unit": "kg",
            "category": "road"
        }
    )

    result = response.json()
    return {
        "co2e": result["co2e"],
        "origin_resolved": result["origin"],      # Hub address
        "destination_resolved": result["destination"],  # Hub address
        "distance": result.get("distance_km")
    }

# Example: Shipment between Madrid and Barcelona hubs
emissions = calculate_hub_to_hub_emissions(
    origin_hub_name="Madrid Distribution Center",
    destination_hub_name="Barcelona Warehouse",
    load_kg=1500
)
print(f"From: {emissions['origin_resolved']}")
print(f"To: {emissions['destination_resolved']}")
print(f"Emissions: {emissions['co2e']} kg CO2e")

You can also mix hub names with addresses:

# Hub to customer address
response = requests.post(
    "https://api.dcycle.io/v1/logistics/requests",
    headers=headers,
    json={
        "origin": "Madrid Distribution Center",  # Hub name
        "destination": "Customer Address, Barcelona, Spain",  # Regular address
        "load": 25,
        "load_unit": "kg",
        "category": "road"
    }
)

Using Known Distance

If you already know the distance, skip geocoding:

def calculate_with_distance(distance_km, load_kg, country="GLO"):
    """Calculate emissions when distance is already known"""
    response = requests.post(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        json={
            "distance_km": distance_km,
            "load": load_kg,
            "load_unit": "kg",
            "category": "road",
            "origin_country": country  # For regional emission factors
        }
    )

    return response.json()

# Example: 500km shipment in Spain
result = calculate_with_distance(500, 1000, "ES")
print(f"CO2e: {result['co2e']} kg")

Comparing Transport Modes

Compare emissions across different transport categories:

def compare_transport_modes(origin, destination, load):
    """Compare emissions for different transport modes"""
    modes = ["road", "rail", "air", "maritime"]
    results = {}

    for mode in modes:
        response = requests.post(
            "https://api.dcycle.io/v1/logistics/requests",
            headers=headers,
            json={
                "origin": origin,
                "destination": destination,
                "load": load,
                "load_unit": "kg",
                "category": mode
            }
        )

        if response.status_code == 200:
            data = response.json()
            results[mode] = data["co2e"]

    return results

# Compare modes for Barcelona to Madrid shipment
comparison = compare_transport_modes(
    "Barcelona, Spain",
    "Madrid, Spain",
    1000
)

for mode, emissions in comparison.items():
    print(f"{mode}: {emissions:.2f} kg CO2e")

Logistics Provider Integration (Full Traceability)

For logistics providers like courier companies that need complete shipment tracking:

def create_tracked_shipment(shipment_data):
    """Create a shipment with full traceability for logistics providers"""
    response = requests.post(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        json={
            # Core emission parameters
            "origin": shipment_data["origin"],
            "destination": shipment_data["destination"],
            "load": shipment_data["weight_kg"],
            "load_unit": "kg",
            "category": "road",
            "origin_country": "ES",

            # Traceability parameters
            "movement_id": shipment_data["tracking_number"],
            "client": shipment_data["client_code"],
            "shipment_date": shipment_data["date"],
            "movement_stretch": shipment_data.get("stretch", "delivery"),
            "movement_stage": shipment_data.get("stage", "last_mile"),
            "vehicle_license_plate": shipment_data.get("vehicle_plate"),
            "trailer_license_plate": shipment_data.get("trailer_plate"),
            "subcontractor": shipment_data.get("is_subcontracted", False),
        }
    )

    return response.json()

# Example: Correos Express shipment
shipment = create_tracked_shipment({
    "tracking_number": "CE-2024-987654",
    "client_code": "CORREOS-EXPRESS",
    "origin": "Centro Logistico Madrid, Spain",
    "destination": "Barcelona, Spain",
    "weight_kg": 25,
    "date": "2024-11-25",
    "stretch": "hub_to_destination",
    "stage": "delivery",
    "vehicle_plate": "1234-ABC",
    "is_subcontracted": False
})

print(f"Tracking: {shipment['movement_id']}")
print(f"CO2e: {shipment['co2e']} kg")

Bulk Shipment Processing

For high-volume scenarios (hundreds to thousands of shipments), use the dedicated bulk endpoint:

Create Logistics Requests (Bulk)

Process up to 5,000 records per request with optimized performance, caching, and partial error handling.

# For bulk processing, use the dedicated bulk endpoint
response = requests.post(
    "https://api.dcycle.io/v1/logistics/requests/bulk",
    headers=headers,
    json={
        "records": shipments,  # List of up to 5,000 records
        "options": {"continue_on_error": True}
    }
)

result = response.json()
print(f"Processed: {result['success']}/{result['total_received']}")
print(f"Total CO2e: {sum(r['co2e'] for r in result['results']):.2f} kg")

Single Package Tracking

Track a single package with one leg (simplest case):

# Create a leg associated with a package
response = requests.post(
    "https://api.dcycle.io/v1/logistics/requests",
    headers=headers,
    json={
        "origin": "Madrid Hub",
        "destination": "Customer Address, Madrid",
        "load": 5,
        "load_unit": "kg",
        "category": "road",

        # Package tracking
        "movement_id": "SHIP-2024-001",      # Shipment identifier
        "package_key": "PKG-2024-000001",    # Unique package identifier

        # Optional
        "client": "AMAZON",
        "shipment_date": "2024-11-25",
    }
)

result = response.json()
print(f"Package {result['package_key']} - CO2e: {result['co2e']} kg")

Multiple Packages in One Shipment

Track multiple packages belonging to the same shipment. Each package has its own package_key but shares the same movement_id:

def create_shipment_with_packages(movement_id: str, packages: list):
    """
    Create a shipment with multiple packages.
    Each package is a single-leg delivery in this example.
    """
    results = []

    for pkg in packages:
        response = requests.post(
            "https://api.dcycle.io/v1/logistics/requests",
            headers=headers,
            json={
                "origin": pkg["origin"],
                "destination": pkg["destination"],
                "load": pkg["weight_kg"],
                "load_unit": "kg",
                "category": "road",

                # Same movement_id groups all packages into one shipment
                "movement_id": movement_id,
                # Each package has unique key
                "package_key": pkg["package_key"],

                "client": pkg.get("client", "DEFAULT"),
            }
        )
        results.append(response.json())

    return results

# Example: Shipment with 3 packages going to different destinations
packages = [
    {"package_key": "PKG-001", "origin": "Madrid Hub", "destination": "Address A, Madrid", "weight_kg": 2, "client": "AMAZON"},
    {"package_key": "PKG-002", "origin": "Madrid Hub", "destination": "Address B, Madrid", "weight_kg": 5, "client": "AMAZON"},
    {"package_key": "PKG-003", "origin": "Madrid Hub", "destination": "Address C, Madrid", "weight_kg": 1, "client": "AMAZON"},
]

results = create_shipment_with_packages("SHIP-2024-100", packages)

total_co2e = sum(r['co2e'] for r in results)
print(f"Shipment SHIP-2024-100: {len(results)} packages, {total_co2e:.2f} kg CO2e total")

# Later, retrieve all packages for this shipment:
# GET /v1/logistics/packages?movement_id=SHIP-2024-100

Multi-leg Package Tracking

Track a package through multiple legs of its journey. Each leg is created separately, and the system automatically aggregates emissions per package:

def track_package_journey(package_key: str, movement_id: str, legs: list):
    """
    Track a package through multiple legs.

    Args:
        package_key: Unique package identifier
        movement_id: Shipment identifier (groups packages)
        legs: List of leg data (origin, destination, load, etc.)
    """
    results = []

    for leg in legs:
        response = requests.post(
            "https://api.dcycle.io/v1/logistics/requests",
            headers=headers,
            json={
                # Core parameters
                "origin": leg["origin"],
                "destination": leg["destination"],
                "load": leg["load_kg"],
                "load_unit": "kg",
                "category": leg.get("category", "road"),

                # Package tracking
                "package_key": package_key,
                "movement_id": movement_id,

                # Optional traceability
                "client": leg.get("client"),
                "shipment_date": leg.get("date"),
            }
        )
        results.append(response.json())

    return results

# Example: Package traveling through 3 legs
legs = [
    {"origin": "Madrid Hub", "destination": "Valencia Hub", "load_kg": 15},
    {"origin": "Valencia Hub", "destination": "Barcelona Hub", "load_kg": 15},
    {"origin": "Barcelona Hub", "destination": "Final Address, Barcelona", "load_kg": 15},
]

results = track_package_journey(
    package_key="PKG-2024-123456",
    movement_id="SHIP-2024-001",
    legs=legs
)

# Get aggregated package data
package_response = requests.get(
    f"https://api.dcycle.io/v1/logistics/packages?movement_id=SHIP-2024-001",
    headers=headers
)
print(f"Total package emissions: {package_response.json()['items'][0]['total_co2e']} kg CO2e")

Migration from Legacy API

If you’re migrating from the legacy /api/v1/logistics/shipment endpoint:

URL Change

Old: /api/v1/logistics/shipmentNew: /v1/logistics/requests

Headers Update

Removed: x-user-id (not needed)Keep: Authorization, x-organization-id

Response Changes

Added: id field for trackingAdded: created_at, updated_at timestamps

Field Names

Most field names remain the sameCheck validation rules for category vs toc

Both APIs will be supported during the migration period. New integrations should use /v1/logistics/requests.

Create Requests (Bulk)

Process up to 5,000 shipments in a single request

Get Logistics Requests

Retrieve all logistics requests (legs) with pagination

Get Packages

Retrieve all packages with aggregated emissions

Get Package by ID

Get a package with all its legs

Get Available Vehicle Types

Retrieve all available TOCs

Authentication Guide

Learn how to get your API key

​Create Logistics Request

​Request

​Headers

​Body Parameters

​Traceability Parameters

​Package Parameters (Multi-leg Shipments)

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​404 Hub Not Found

​400 Hub Has No Address

​Use Cases

​Calculate Emissions with Addresses

​Using Hub Names for Origin/Destination

​Using Known Distance

​Comparing Transport Modes

​Logistics Provider Integration (Full Traceability)

​Bulk Shipment Processing

Create Logistics Requests (Bulk)

​Single Package Tracking

​Multiple Packages in One Shipment

​Multi-leg Package Tracking

​Migration from Legacy API

URL Change

Headers Update

Response Changes

Field Names

​Related Endpoints

Create Requests (Bulk)

Get Logistics Requests

Get Packages

Get Package by ID

Get Available Vehicle Types

Authentication Guide

Create Logistics Request

Request

Headers

Body Parameters

Traceability Parameters

Package Parameters (Multi-leg Shipments)

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

404 Hub Not Found

400 Hub Has No Address

Use Cases

Calculate Emissions with Addresses

Using Hub Names for Origin/Destination

Using Known Distance

Comparing Transport Modes

Logistics Provider Integration (Full Traceability)

Bulk Shipment Processing

Single Package Tracking

Multiple Packages in One Shipment

Multi-leg Package Tracking

Migration from Legacy API

Related Endpoints