Skip to main content
GET
/
v1
/
logistics
/
requests
Get Logistics Requests
const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/logistics/requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "page": 123,
  "size": 123,
  "total": 123,
  "items": [
    {
      "id": "<string>",
      "origin": "<string>",
      "destination": "<string>",
      "origin_country": "<string>",
      "distance_km": 123,
      "load": 123,
      "load_unit": "<string>",
      "load_factor": 123,
      "toc": "<string>",
      "category": "<string>",
      "year": 123,
      "cleaning": true,
      "subcontractor": true,
      "hub_id": "<string>",
      "co2e": 123,
      "created_at": {},
      "updated_at": {},
      "package_id": "<string>",
      "package_key": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://code.dcycle.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Get Logistics Requests

Retrieve all logistics requests created by your organization with pagination support.
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

​
Query Parameters

​
page
integer
default:"1"
Page number to retrieveExample: 1
​
size
integer
default:"10"
Number of items per page (1-100)Example: 50

​
Response

​
page
integer
Current page number
​
size
integer
Number of items per page
​
total
integer
Total number of logistics requests
​
items
array
Array of logistics request objects

​
Example

curl -X GET "https://api.dcycle.io/v1/logistics/requests?page=1&size=10" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

​
Successful Response

{
  "page": 1,
  "size": 10,
  "total": 42,
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "origin_country": "ES",
      "distance_km": 621.5,
      "load": 1000,
      "load_unit": "kg",
      "load_factor": 1.0,
      "toc": "van_diesel",
      "category": "road",
      "year": 2024,
      "cleaning": false,
      "subcontractor": false,
      "hub_id": null,
      "co2e": 245.5,
      "created_at": "2024-11-24T10:30:00Z",
      "updated_at": "2024-11-24T10:30:00Z"
    },
    {
      "id": "a12bc34d-56ef-7890-ghij-klmnopqrstuv",
      "origin": "Paris, France",
      "destination": "Berlin, Germany",
      "origin_country": "FR",
      "distance_km": 1054.3,
      "load": 2500,
      "load_unit": "kg",
      "load_factor": 0.8,
      "toc": "rigid_truck_7.5_12_t_gvw_average_diesel",
      "category": "road",
      "year": 2024,
      "cleaning": false,
      "subcontractor": true,
      "hub_id": "b3d2e1f0-1234-5678-abcd-ef0123456789",
      "co2e": 512.8,
      "created_at": "2024-11-23T14:15:00Z",
      "updated_at": "2024-11-23T14:15:00Z"
    }
  ]
}

​
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: Invalid pagination parameters 
{
  "detail": [
    {
      "loc": ["query", "size"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error"
    }
  ]
}
Solution: Ensure page is a positive integer and size is between 1 and 100.

​
Use Cases

​
List All Logistics Requests

Retrieve all logistics requests with default pagination: 
def get_all_logistics_requests():
    """Retrieve all logistics requests with pagination"""
    all_requests = []
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/logistics/requests",
            headers=headers,
            params={"page": page, "size": 100}
        )

        data = response.json()
        all_requests.extend(data['items'])

        # Check if we've retrieved all pages
        if len(data['items']) < data['size']:
            break

        page += 1

    return all_requests

# Example usage
all_requests = get_all_logistics_requests()
print(f"Total logistics requests: {len(all_requests)}")

​
Filter and Analyze Requests

Retrieve requests and analyze by transport category: 
def analyze_logistics_by_category():
    """Analyze logistics requests by transport category"""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        params={"page": 1, "size": 100}
    )

    data = response.json()

    # Group by category
    by_category = {}
    for item in data['items']:
        category = item['category']
        if category not in by_category:
            by_category[category] = []
        by_category[category].append(item)

    # Print summary
    for category, items in by_category.items():
        total_distance = sum(item['distance_km'] or 0 for item in items)
        total_co2e = sum(item['co2e'] for item in items)
        print(f"{category}:")
        print(f"  - Requests: {len(items)}")
        print(f"  - Total distance: {total_distance:.2f} km")
        print(f"  - Total emissions: {total_co2e:.2f} kg CO2e")

# Example usage
analyze_logistics_by_category()

​
Export to CSV

Export logistics requests to a CSV file: 
import csv

def export_logistics_to_csv(filename="logistics_requests.csv"):
    """Export all logistics requests to CSV"""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        params={"page": 1, "size": 100}
    )

    data = response.json()

    # Define CSV fields
    fields = ['id', 'origin', 'destination', 'distance_km', 'load',
              'load_unit', 'category', 'co2e', 'created_at']

    with open(filename, 'w', newline='') as csvfile:
        writer = csv.DictWriter(csvfile, fieldnames=fields)
        writer.writeheader()

        for item in data['items']:
            # Extract only the fields we want
            row = {field: item.get(field) for field in fields}
            writer.writerow(row)

    print(f"Exported {len(data['items'])} requests to {filename}")

# Example usage
export_logistics_to_csv()

Create Logistics Request

Calculate emissions for a new leg

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