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

import requests

url = "https://api.dcycle.io/v1/logistics/packages/{package_id}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

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

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

import requests

url = "https://api.dcycle.io/v1/logistics/packages/{package_id}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Path Parameters

string

required

The UUID of the package to retrieveExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

string

Unique identifier for the package (UUID)

string

Shipment identifier (groups packages from the same shipment)

string

Unique package identifier provided during creation

string

Client billing identifier (optional)

number

Package weight in kilograms

number

Total distance across all legs in kilometers

number

Total CO2 equivalent emissions across all legs in kilograms

string

Package status (active, inactive)

datetime

Timestamp when the package was created

datetime | null

Timestamp when the package was last updated

array

Array of leg objects associated with this package

Show Leg Object

string

Unique identifier for the leg (UUID)

string

Origin location of the leg

string

Destination location of the leg

number

Distance of this leg in kilometers

number

CO2 equivalent emissions for this leg in kilograms

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

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
}

package_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.get(
    f"https://api.dcycle.io/v1/logistics/packages/{package_id}",
    headers=headers
)

package = response.json()
print(f"Package: {package['package_key']}")
print(f"Total emissions: {package['total_co2e']:.2f} kg CO2e")
print(f"Legs ({len(package['legs'])}):")
for leg in package['legs']:
    print(f"  - {leg['origin']} -> {leg['destination']}: {leg['co2e']:.2f} kg CO2e")

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
};

const packageId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

axios.get(
  `https://api.dcycle.io/v1/logistics/packages/${packageId}`,
  { headers }
)
.then(response => {
  const pkg = response.data;
  console.log(`Package: ${pkg.package_key}`);
  console.log(`Total emissions: ${pkg.total_co2e?.toFixed(2)} kg CO2e`);
  console.log(`Legs (${pkg.legs.length}):`);
  pkg.legs.forEach(leg => {
    console.log(`  - ${leg.origin} -> ${leg.destination}: ${leg.co2e?.toFixed(2)} kg CO2e`);
  });
})
.catch(error => console.error(error));

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:

The package_id is a valid UUID
The package belongs to the organization specified in x-organization-id
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

​Get Package by ID

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​Use Cases

​Detailed Package Journey Analysis

​Generate Package Certificate Data

​Related Endpoints

Get Packages

Create Logistics Request

Get Logistics Requests

Authentication Guide

Get Package by ID

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

Use Cases

Detailed Package Journey Analysis

Generate Package Certificate Data

Related Endpoints