Skip to main content
GET
/
v1
/
logistics
/
packages
/
{package_id}
Get Package by ID
const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/logistics/packages/{package_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "<string>",
  "shipment_id": "<string>",
  "package_key": "<string>",
  "client_billing_id": "<string>",
  "weight_kg": 123,
  "total_distance_km": 123,
  "total_co2e": 123,
  "status": "<string>",
  "created_at": {},
  "updated_at": {},
  "legs": [
    {
      "id": "<string>",
      "origin": "<string>",
      "destination": "<string>",
      "distance_km": 123,
      "co2e": 123
    }
  ]
}

​
Get Package by ID

Retrieve a specific logistics package by its UUID, including all associated legs and aggregated emissions data.
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

​
Path Parameters

​
package_id
string
required
The UUID of the package to retrieveExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Response

​
id
string
Unique identifier for the package (UUID)
​
shipment_id
string
Shipment identifier (groups packages from the same shipment)
​
package_key
string
Unique package identifier provided during creation
​
client_billing_id
string
Client billing identifier (optional)
​
weight_kg
number
Package weight in kilograms
​
total_distance_km
number
Total distance across all legs in kilometers
​
total_co2e
number
Total CO2 equivalent emissions across all legs in kilograms
​
status
string
Package status (active, inactive)
​
created_at
datetime
Timestamp when the package was created
​
updated_at
datetime
Timestamp when the package was last updated
​
legs
array
Array of leg objects associated with this package

​
Example

curl -X GET "https://api.dcycle.io/v1/logistics/packages/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

​
Successful Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "shipment_id": "SHIP-2024-001",
  "package_key": "PKG-2024-123456",
  "client_billing_id": "CLIENT-001",
  "weight_kg": 15.0,
  "total_distance_km": 850.5,
  "total_co2e": 42.75,
  "status": "active",
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T14:45:00Z",
  "legs": [
    {
      "id": "leg-uuid-1",
      "origin": "Madrid Hub",
      "destination": "Valencia Hub",
      "distance_km": 350.2,
      "co2e": 17.51
    },
    {
      "id": "leg-uuid-2",
      "origin": "Valencia Hub",
      "destination": "Barcelona Hub",
      "distance_km": 350.3,
      "co2e": 17.52
    },
    {
      "id": "leg-uuid-3",
      "origin": "Barcelona Hub",
      "destination": "Final Address, Barcelona",
      "distance_km": 150.0,
      "co2e": 7.72
    }
  ]
}

​
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: Package not found or doesn’t belong to your organization 
{
  "code": "NOT_FOUND",
  "detail": "Package not found"
}
Solution: Verify that:
  1. The package_id is a valid UUID
  2. The package belongs to the organization specified in x-organization-id
  3. The package exists and hasn’t been deleted

​
Use Cases

​
Detailed Package Journey Analysis

Analyze the complete journey of a package: 
def analyze_package_journey(package_id: str) -> dict:
    """Analyze a package's complete journey"""
    response = requests.get(
        f"https://api.dcycle.io/v1/logistics/packages/{package_id}",
        headers=headers
    )

    package = response.json()
    legs = package.get('legs', [])

    # Calculate metrics
    journey = {
        "package_key": package['package_key'],
        "total_legs": len(legs),
        "total_distance_km": package['total_distance_km'],
        "total_co2e_kg": package['total_co2e'],
        "average_co2e_per_km": (
            package['total_co2e'] / package['total_distance_km']
            if package['total_distance_km'] else 0
        ),
        "journey_details": [
            {
                "leg": i + 1,
                "route": f"{leg['origin']} -> {leg['destination']}",
                "distance_km": leg['distance_km'],
                "co2e_kg": leg['co2e'],
                "percentage_of_total": (
                    (leg['co2e'] / package['total_co2e'] * 100)
                    if package['total_co2e'] else 0
                )
            }
            for i, leg in enumerate(legs)
        ]
    }

    return journey

# Example usage
analysis = analyze_package_journey("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print(f"Package {analysis['package_key']} Journey:")
print(f"  Total legs: {analysis['total_legs']}")
print(f"  Total distance: {analysis['total_distance_km']:.2f} km")
print(f"  Total emissions: {analysis['total_co2e_kg']:.2f} kg CO2e")
print(f"\nLeg breakdown:")
for leg in analysis['journey_details']:
    print(f"  Leg {leg['leg']}: {leg['route']}")
    print(f"    Distance: {leg['distance_km']:.2f} km")
    print(f"    Emissions: {leg['co2e_kg']:.2f} kg ({leg['percentage_of_total']:.1f}%)")

​
Generate Package Certificate Data

Prepare data for an emissions certificate: 
def get_package_certificate_data(package_id: str) -> dict:
    """Get data for generating an emissions certificate"""
    response = requests.get(
        f"https://api.dcycle.io/v1/logistics/packages/{package_id}",
        headers=headers
    )

    package = response.json()

    certificate_data = {
        "certificate_type": "Package Emissions Report",
        "package_identifier": package['package_key'],
        "shipment_reference": package['shipment_id'],
        "weight_transported_kg": package['weight_kg'],
        "total_distance_km": package['total_distance_km'],
        "total_co2e_kg": package['total_co2e'],
        "legs_count": len(package.get('legs', [])),
        "calculation_date": package['updated_at'],
        "route_summary": " -> ".join(
            [package['legs'][0]['origin']] +
            [leg['destination'] for leg in package.get('legs', [])]
        ) if package.get('legs') else "N/A"
    }

    return certificate_data

# Example usage
cert = get_package_certificate_data("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print("=== EMISSIONS CERTIFICATE ===")
print(f"Package: {cert['package_identifier']}")
print(f"Shipment: {cert['shipment_reference']}")
print(f"Route: {cert['route_summary']}")
print(f"Weight: {cert['weight_transported_kg']} kg")
print(f"Distance: {cert['total_distance_km']:.2f} km")
print(f"CO2e Emissions: {cert['total_co2e_kg']:.2f} kg")

Get Packages

List all packages with pagination

Create Logistics Request

Create a new leg (with optional package association)

Get Logistics Requests

Retrieve all legs with pagination

Authentication Guide

Learn how to get your API key