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

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

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

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

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

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

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")

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")

# 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"
    }
)

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")

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")

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")

# 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")

# 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")

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

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")