Get Logistics Requests

const options = {
  method: 'GET',
  headers: {'x-organization-id': '<x-organization-id>', 'x-api-key': '<api-key>'}
};

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-organization-id": "<x-organization-id>",
    "x-api-key": "<api-key>"
}

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

print(response.text)

{
  "page": 1,
  "size": 50,
  "total": 100,
  "items": [
    {
      "id": "<string>",
      "load_unit": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "origin": "<string>",
      "destination": "<string>",
      "distance_km": 123,
      "load": 123,
      "toc": "<string>",
      "cleaning": true,
      "status": "active",
      "movement_id": "<string>",
      "client": "<string>",
      "shipment_date": "2023-12-25",
      "movement_stretch": "<string>",
      "movement_stage": "<string>",
      "vehicle_license_plate": "<string>",
      "trailer_license_plate": "<string>",
      "subcontractor": true,
      "hub_id": "<string>",
      "tkm": 123,
      "kgco2e": 123,
      "emission_intensity": 123,
      "error_messages": [
        "<string>"
      ],
      "estimated_data": [
        "<string>"
      ],
      "file_name": "<string>",
      "uploaded_by": {
        "first_name": "<string>",
        "last_name": "<string>",
        "profile_img_url": "<string>"
      },
      "linked_projects": [
        {
          "project_id": "<string>",
          "project_name": "<string>",
          "project_type": "carbon_footprint",
          "project_methodology": "esrs",
          "organization_id": "<string>",
          "organization_name": "<string>"
        }
      ]
    }
  ],
  "filter_hash": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

GET

logistics

requests

Get Logistics Requests

const options = {
  method: 'GET',
  headers: {'x-organization-id': '<x-organization-id>', 'x-api-key': '<api-key>'}
};

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-organization-id": "<x-organization-id>",
    "x-api-key": "<api-key>"
}

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

print(response.text)

{
  "page": 1,
  "size": 50,
  "total": 100,
  "items": [
    {
      "id": "<string>",
      "load_unit": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "origin": "<string>",
      "destination": "<string>",
      "distance_km": 123,
      "load": 123,
      "toc": "<string>",
      "cleaning": true,
      "status": "active",
      "movement_id": "<string>",
      "client": "<string>",
      "shipment_date": "2023-12-25",
      "movement_stretch": "<string>",
      "movement_stage": "<string>",
      "vehicle_license_plate": "<string>",
      "trailer_license_plate": "<string>",
      "subcontractor": true,
      "hub_id": "<string>",
      "tkm": 123,
      "kgco2e": 123,
      "emission_intensity": 123,
      "error_messages": [
        "<string>"
      ],
      "estimated_data": [
        "<string>"
      ],
      "file_name": "<string>",
      "uploaded_by": {
        "first_name": "<string>",
        "last_name": "<string>",
        "profile_img_url": "<string>"
      },
      "linked_projects": [
        {
          "project_id": "<string>",
          "project_name": "<string>",
          "project_type": "carbon_footprint",
          "project_methodology": "esrs",
          "organization_id": "<string>",
          "organization_name": "<string>"
        }
      ]
    }
  ],
  "filter_hash": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Get Logistics Requests

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.

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

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

Authorizations

x-api-key

string

header

required

Headers

x-api-key

string

x-organization-id

string<uuid>

required

Query Parameters

page

integer

default:1

Required range: x >= 1

size

integer

default:10

Required range: 1 <= x <= 500

project_id

string<uuid>

string

Search across movement ID and stretch ID

clients[]

string[]

Filter by client name(s)

trip_date_from

string

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

trip_date_until

string

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

vehicle_type[]

string[]

Filter by vehicle type(s)

trip_status

string

Filter by trip status

uploaded_by[]

string<uuid>[]

Filter by uploader user ID(s)

file_id[]

string<uuid>[]

Filter by file ID(s)

created_at_from

string

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

created_at_to

string

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

Response

Successful Response

Response schema for paginated logistics requests.

page

integer

required

Current page number

Example:

1

size

integer

required

Number of items per page

Example:

50

total

integer

required

Total number of items

Example:

100

items

GetLogisticsRequestOut · object[]

required

List of logistics requests

Hide child attributes

items.id

string

required

items.load_unit

string

required

items.created_at

string<date-time>

required

items.origin

string

items.destination

string

items.distance_km

number

items.load

number

items.toc

string

items.cleaning

boolean

items.status

string

default:active

items.movement_id

string

items.client

string

items.shipment_date

string<date>

items.movement_stretch

string

items.movement_stage

string

items.vehicle_license_plate

string

items.trailer_license_plate

string

items.subcontractor

boolean

items.hub_id

string

items.tkm

number

items.kgco2e

number

items.emission_intensity

number

items.error_messages

string[]

items.estimated_data

string[]

items.file_name

string

items.uploaded_by

UploadedBySch · object

User info for uploaded_by field.

Hide child attributes

items.uploaded_by.first_name

string

items.uploaded_by.last_name

string

items.uploaded_by.profile_img_url

string

items.linked_projects

LinkedProjectSch · object[]

Hide child attributes

items.linked_projects.project_id

string

required

items.linked_projects.project_name

string

required

items.linked_projects.project_type

enum<string>

Project type.

Available options:

carbon_footprint,

custom,

einf,

iso_14064,

iso_14001,

iso_9001,

lca,

visualization,

suppliers,

logistics

items.linked_projects.project_methodology

enum<string>

Project methodology.

Available options:

esrs,

gri,

glec,

custom

items.linked_projects.organization_id

string

items.linked_projects.organization_name

string

filter_hash

string

Hash of the applied filters

​Get Logistics Requests

​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

Get Packages

Get Package by ID

Get Available Vehicle Types

Authentication Guide

Authorizations

Headers

Query Parameters

Response

Get Logistics Requests

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