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

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

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

Body Parameters

origin

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"

destination

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.

distance_km

number

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

load

number

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

load_unit

string

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

load_factor

number

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

toc

string

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

Traceability Parameters

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

movement_id

string

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

client

string

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

shipment_date

date

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

movement_stretch

string

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

movement_stage

string

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

vehicle_license_plate

string

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

trailer_license_plate

string

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

subcontractor

boolean

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

tkm

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

hub_id

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.

package_key

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

co2e

number

Total CO2 equivalent emissions in kilograms

created_at

datetime

Timestamp when the request was created

updated_at

datetime

Timestamp when the request was last updated

origin

string

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

destination

string

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

distance_km

number

Distance in kilometers (if provided or calculated)

load

number

Transported load

load_unit

string

Load unit of measurement

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"
  }'

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

Introduction

Logistics

Vehicles

Unknown Vehicles

Vehicle Fuels

Business Travels

Employees

Commuting Periods

Invoices

Purchases

​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