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

import requests

url = "https://api.dcycle.io/v1/logistics/requests"

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

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

print(response.text)

{
  "page": 123,
  "size": 123,
  "total": 123,
  "items": {
    "id": "<string>",
    "movement_id": {},
    "client": {},
    "shipment_date": {},
    "origin": {},
    "destination": {},
    "distance_km": {},
    "load": {},
    "load_unit": "<string>",
    "toc": {},
    "category": {},
    "status": "<string>",
    "kgco2e": {},
    "emission_intensity": {},
    "tkm": {},
    "cleaning": {},
    "movement_stretch": {},
    "movement_stage": {},
    "vehicle_license_plate": {},
    "trailer_license_plate": {},
    "subcontractor": {},
    "hub_id": {},
    "created_at": {}
  },
  "filter_hash": {}
}

GET

logistics

requests

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

import requests

url = "https://api.dcycle.io/v1/logistics/requests"

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

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

print(response.text)

{
  "page": 123,
  "size": 123,
  "total": 123,
  "items": {
    "id": "<string>",
    "movement_id": {},
    "client": {},
    "shipment_date": {},
    "origin": {},
    "destination": {},
    "distance_km": {},
    "load": {},
    "load_unit": "<string>",
    "toc": {},
    "category": {},
    "status": "<string>",
    "kgco2e": {},
    "emission_intensity": {},
    "tkm": {},
    "cleaning": {},
    "movement_stretch": {},
    "movement_stage": {},
    "vehicle_license_plate": {},
    "trailer_license_plate": {},
    "subcontractor": {},
    "hub_id": {},
    "created_at": {}
  },
  "filter_hash": {}
}

← Logistics API Retrieve logistics requests created by your organization with pagination and filtering support.

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

Query Parameters

integer

default:"1"

Page number for pagination

integer

default:"50"

Number of items per page

string

Search across movement ID and stretch ID

uuid

Filter by project UUID

array[string]

Filter by client name(s)

string

Filter by trip date >= value (YYYY-MM-DD)

string

Filter by trip date <= value (YYYY-MM-DD)

array[string]

Filter by vehicle type(s) (TOC codes)

string

Filter by trip status (e.g. active, deleted)

array[uuid]

Filter by uploader user UUID(s)

array[uuid]

Filter by source file UUID(s)

string

Filter by created_at >= value (YYYY-MM-DD)

string

Filter by created_at <= value (YYYY-MM-DD)

Response

Returns a paginated list of logistics requests with HTTP 200.

integer

Current page number

integer

Number of items per page

integer

Total number of matching items

array[object]

List of logistics request objects

Show Request object

string

Request UUID

string | null

Movement tracking identifier

string | null

Client name

string | null

Shipment date (YYYY-MM-DD)

string | null

Origin location

string | null

Destination location

number | null

Calculated distance in kilometers

number | null

Load weight

string

Load unit (e.g. kg, t)

string | null

Transport operation category (vehicle type)

string | null

Transport category (e.g. road, sea, air)

string

Record status: active or deleted

number | null

Calculated emissions in kg CO2e (null if pending)

number | null

Emission intensity (kgCO2e per tonne-km)

number | null

Tonne-kilometers

boolean | null

Whether cleaning is required

string | null

Movement stretch identifier

string | null

Movement stage

string | null

Vehicle license plate

string | null

Trailer license plate

boolean | null

Whether this leg is subcontracted

string | null

UUID of the associated logistic hub

datetime

Creation timestamp (ISO 8601)

string | null

Hash of the applied filters (for caching)

Example

curl --get "https://api.dcycle.io/v1/logistics/requests" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  --data-urlencode "page=1" \
  --data-urlencode "size=50" \
  --data-urlencode "search=MOV-2024" \
  --data-urlencode "trip_date_from=2024-01-01" \
  --data-urlencode "trip_date_until=2024-12-31" \
  --data-urlencode "clients[]=Acme Logistics"

import os

import requests

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

params = [
    ("page", 1),
    ("size", 50),
    ("search", "MOV-2024"),
    ("trip_date_from", "2024-01-01"),
    ("trip_date_until", "2024-12-31"),
    ("clients[]", "Acme Logistics"),
]

response = requests.get(
    "https://api.dcycle.io/v1/logistics/requests",
    headers=headers,
    params=params,
)
response.raise_for_status()

result = response.json()
print(f"Total requests: {result['total']}")
print(f"Page {result['page']} of {max(1, (result['total'] + result['size'] - 1) // result['size'])}")

for item in result["items"]:
    emissions = item["kgco2e"] if item["kgco2e"] is not None else "pending"
    print(f"- {item['movement_id']}: {item['client']} | {item['origin']} to {item['destination']} | {emissions} kgCO2e")

const axios = require("axios");

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const params = new URLSearchParams({
  page: "1",
  size: "50",
  search: "MOV-2024",
  trip_date_from: "2024-01-01",
  trip_date_until: "2024-12-31"
});
params.append("clients[]", "Acme Logistics");

axios.get("https://api.dcycle.io/v1/logistics/requests", {
  headers: {
    "x-api-key": apiKey,
    "x-organization-id": orgId
  },
  params
})
.then(response => {
  const { page, size, total, items } = response.data;
  console.log(`Page ${page} of ${Math.max(1, Math.ceil(total / size))}`);

  items.forEach(item => {
    const emissions = item.kgco2e ?? "pending";
    console.log(`- ${item.movement_id}: ${item.client} | ${item.origin} to ${item.destination} | ${emissions} kgCO2e`);
  });
})
.catch(error => console.error(error));

Successful Response

{
  "items": [
    {
      "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "movement_id": "MOV-2024-001234",
      "client": "Acme Logistics",
      "shipment_date": "2024-06-15",
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "distance_km": 621.5,
      "load": 1000,
      "load_unit": "kg",
      "toc": "truck_diesel",
      "category": "road",
      "status": "active",
      "kgco2e": 45.2,
      "emission_intensity": 0.0452,
      "created_at": "2024-06-15T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 50
}

Use Cases

List All Logistics Requests

Retrieve every page of logistics requests:

def get_all_logistics_requests(headers):
    """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": 500},
        )
        response.raise_for_status()

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

        if page * data["size"] >= data["total"]:
            break

        page += 1

    return all_requests

Filter by Project and Date

Scope logistics requests to a project and shipment date range:

def get_project_requests(headers, project_id):
    """Retrieve logistics requests linked to a project for 2024."""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        params={
            "page": 1,
            "size": 100,
            "project_id": project_id,
            "trip_date_from": "2024-01-01",
            "trip_date_until": "2024-12-31",
        },
    )
    response.raise_for_status()
    return response.json()

Export to CSV

Export the current filtered page to a CSV file:

import csv


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

    data = response.json()
    fields = [
        "id",
        "movement_id",
        "client",
        "shipment_date",
        "origin",
        "destination",
        "distance_km",
        "load",
        "load_unit",
        "toc",
        "status",
        "kgco2e",
        "emission_intensity",
        "created_at",
    ]

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

        for item in data["items"]:
            writer.writerow({field: item.get(field) for field in fields})

    return len(data["items"])

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

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

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

Create Logistics Request

Calculate emissions for a new leg

List Packages

Retrieve all packages with aggregated emissions

Get Package by ID

Get a package with all its legs

List Available Vehicle Types

Retrieve all available TOCs

Authentication Guide

Learn how to get your API key

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Use Cases

​List All Logistics Requests

​Filter by Project and Date

​Export to CSV

​Common Errors

​401 Unauthorized

​403 Forbidden

​Related Endpoints

Create Logistics Request

List Packages

Get Package by ID

List Available Vehicle Types

Authentication Guide

Request

Headers

Query Parameters

Response

Example

Successful Response

Use Cases

List All Logistics Requests

Filter by Project and Date

Export to CSV

Common Errors

401 Unauthorized

403 Forbidden

Related Endpoints