Generate Report

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

fetch('https://api.dcycle.io/v1/logistics/report', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

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

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

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

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/logistics/report \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "client": "<string>",
  "period": {
    "start_date": "<string>",
    "end_date": "<string>"
  },
  "summary": {
    "total_items": 123,
    "total_co2e_kg": 123,
    "total_distance_km": 123,
    "avg_co2e_per_item": 123
  },
  "by_category": [
    {
      "category": "<string>",
      "items": 123,
      "co2e_kg": 123,
      "distance_km": 123,
      "percentage_co2e": 123
    }
  ],
  "by_fleet_type": [
    {
      "fleet_type": "<string>",
      "items": 123,
      "co2e_kg": 123,
      "distance_km": 123,
      "percentage_items": 123,
      "percentage_distance": 123,
      "percentage_co2e": 123
    }
  ],
  "electrification_savings": {
    "electric_trips": 123,
    "actual_co2e_kg": 123,
    "hypothetical_diesel_co2e_kg": 123,
    "avoided_co2e_kg": 123,
    "percentage_reduction": 123
  },
  "data_source": "<string>",
  "methodology": "<string>"
}

GET

logistics

report

Generate Report

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

fetch('https://api.dcycle.io/v1/logistics/report', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

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

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

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

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/logistics/report \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "client": "<string>",
  "period": {
    "start_date": "<string>",
    "end_date": "<string>"
  },
  "summary": {
    "total_items": 123,
    "total_co2e_kg": 123,
    "total_distance_km": 123,
    "avg_co2e_per_item": 123
  },
  "by_category": [
    {
      "category": "<string>",
      "items": 123,
      "co2e_kg": 123,
      "distance_km": 123,
      "percentage_co2e": 123
    }
  ],
  "by_fleet_type": [
    {
      "fleet_type": "<string>",
      "items": 123,
      "co2e_kg": 123,
      "distance_km": 123,
      "percentage_items": 123,
      "percentage_distance": 123,
      "percentage_co2e": 123
    }
  ],
  "electrification_savings": {
    "electric_trips": 123,
    "actual_co2e_kg": 123,
    "hypothetical_diesel_co2e_kg": 123,
    "avoided_co2e_kg": 123,
    "percentage_reduction": 123
  },
  "data_source": "<string>",
  "methodology": "<string>"
}

Generate ISO 14083 Report

Generate a complete logistics emissions report following ISO 14083 methodology. Includes aggregated KPIs, breakdowns by transport category, fleet-type analysis, and electrification savings.

New API: This endpoint is part of the new API architecture with improved design and maintainability. It automatically detects whether to use packages (new API) or requests (legacy API) based on your data.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Query Parameters

string

required

Period start date (format: YYYY-MM-DD)Example: 2025-01-01

string

required

Period end date (format: YYYY-MM-DD)Example: 2025-12-31

string

Filter by client identifier (optional)Example: AMAZON

uuid

Filter the report by project UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Response

string

Client filter applied (null if not filtered)

object

Show properties

date

Start date (YYYY-MM-DD)

date

End date (YYYY-MM-DD)

object

Show properties

integer

Total number of packages (new API) or shipments (legacy)

number

Total emissions in kg CO2e

number

Total distance in km

number

Average CO2e per package/shipment

array

Breakdown by transport category

Show properties

string

Transport category (road, rail, maritime, air)

integer

Number of packages/shipments

number

Emissions in kg CO2e

number

Distance in km

number

Percentage of total emissions

array

Breakdown by fleet type — cross-tabulation of ownership (own vs third-party) and energy type (conventional, electrified, renewable)

Show properties

string

Fleet type key in format {ownership}_{energy}. Possible values: own_conventional, own_electrified, own_renewable, third_party_conventional, third_party_electrified, third_party_renewable, own_unknown, third_party_unknown

integer

Number of shipments/legs

number

Emissions in kg CO2e

number

Distance in km

number

Percentage of total trips

number

Percentage of total distance

number

Percentage of total CO2e

object

Electrification savings analysis comparing actual electric trip emissions vs hypothetical diesel equivalent. null when no electric trips exist in the period.

Show properties

integer

Number of electric trips/legs

number

Actual CO2e from electric trips (kg)

number

Hypothetical CO2e if those trips used diesel equivalents (kg)

number

CO2e avoided vs diesel (can be negative if electric WTW exceeds diesel WTW)

number

Percentage reduction vs diesel

string

Source of data: packages (new API) or requests (legacy API)

string

Methodology used (always “ISO 14083”)

Example

curl -X GET "https://api.dcycle.io/v1/logistics/report?start_date=2025-01-01&end_date=2025-12-31&client=AMAZON" \
  -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
}

params = {
    "start_date": "2025-01-01",
    "end_date": "2025-12-31",
    "client": "AMAZON"  # Optional
}

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

report = response.json()
print(f"Total CO2e: {report['summary']['total_co2e_kg']:.2f} kg")
print(f"Total packages: {report['summary']['total_items']}")
print(f"Data source: {report['data_source']}")

# Fleet type breakdown
for ft in report.get("by_fleet_type", []):
    print(f"  {ft['fleet_type']}: {ft['co2e_kg']:.2f} kg ({ft['percentage_co2e']}%)")

# Electrification savings
savings = report.get("electrification_savings")
if savings:
    print(f"Electric trips: {savings['electric_trips']}")
    print(f"CO2e avoided: {savings['avoided_co2e_kg']:.2f} kg ({savings['percentage_reduction']}% reduction)")

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 params = {
  start_date: '2025-01-01',
  end_date: '2025-12-31',
  client: 'AMAZON'  // Optional
};

axios.get(
  'https://api.dcycle.io/v1/logistics/report',
  { headers, params }
)
.then(response => {
  const { summary, by_fleet_type, electrification_savings, data_source } = response.data;
  console.log(`Total CO2e: ${summary.total_co2e_kg.toFixed(2)} kg`);
  console.log(`Total packages: ${summary.total_items}`);
  console.log(`Data source: ${data_source}`);

  by_fleet_type.forEach(ft => {
    console.log(`  ${ft.fleet_type}: ${ft.co2e_kg.toFixed(2)} kg (${ft.percentage_co2e}%)`);
  });

  if (electrification_savings) {
    console.log(`CO2e avoided: ${electrification_savings.avoided_co2e_kg.toFixed(2)} kg`);
  }
})
.catch(error => console.error(error));

Successful Response

{
  "client": "AMAZON",
  "period": {
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "summary": {
    "total_items": 1500,
    "total_co2e_kg": 12500.50,
    "total_distance_km": 45000.00,
    "avg_co2e_per_item": 8.3337
  },
  "by_category": [
    {
      "category": "road",
      "items": 1400,
      "co2e_kg": 11000.00,
      "distance_km": 40000.00,
      "percentage_co2e": 88.0
    },
    {
      "category": "rail",
      "items": 100,
      "co2e_kg": 1500.50,
      "distance_km": 5000.00,
      "percentage_co2e": 12.0
    }
  ],
  "by_fleet_type": [
    {
      "fleet_type": "own_conventional",
      "items": 900,
      "co2e_kg": 8500.00,
      "distance_km": 28000.00,
      "percentage_items": 60.0,
      "percentage_distance": 62.2,
      "percentage_co2e": 68.0
    },
    {
      "fleet_type": "own_electrified",
      "items": 200,
      "co2e_kg": 400.50,
      "distance_km": 5000.00,
      "percentage_items": 13.3,
      "percentage_distance": 11.1,
      "percentage_co2e": 3.2
    },
    {
      "fleet_type": "third_party_conventional",
      "items": 400,
      "co2e_kg": 3600.00,
      "distance_km": 12000.00,
      "percentage_items": 26.7,
      "percentage_distance": 26.7,
      "percentage_co2e": 28.8
    }
  ],
  "electrification_savings": {
    "electric_trips": 200,
    "actual_co2e_kg": 400.50,
    "hypothetical_diesel_co2e_kg": 2800.00,
    "avoided_co2e_kg": 2399.50,
    "percentage_reduction": 85.7
  },
  "data_source": "packages",
  "methodology": "ISO 14083"
}

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.

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 date format

{
  "detail": "Invalid date format. Use YYYY-MM-DD"
}

Solution: Use the YYYY-MM-DD format (for example: 2025-01-01)

Use Cases

Annual Report

Generate the complete annual report for sustainability audits:

def generate_annual_report(year, client=None):
    """Generate annual ISO 14083 report"""
    params = {
        "start_date": f"{year}-01-01",
        "end_date": f"{year}-12-31"
    }
    if client:
        params["client"] = client

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

    report = response.json()

    # Convert to tonnes for reporting
    total_tonnes = report['summary']['total_co2e_kg'] / 1000

    print(f"Annual Emissions Report {year}")
    print("=" * 40)
    print(f"Total emissions: {total_tonnes:.2f} tCO2e")
    print(f"Total packages: {report['summary']['total_items']}")
    print(f"Average per package: {report['summary']['avg_co2e_per_item']:.2f} kgCO2e")

    return report

# Generate for all clients
annual = generate_annual_report(2025)

# Generate for specific client
amazon_report = generate_annual_report(2025, client="AMAZON")

Monthly Comparison

Compare emissions month by month:

import calendar

def monthly_comparison(year, client=None):
    """Compare emissions by month"""
    monthly_data = []

    for month in range(1, 13):
        last_day = calendar.monthrange(year, month)[1]

        params = {
            "start_date": f"{year}-{month:02d}-01",
            "end_date": f"{year}-{month:02d}-{last_day}"
        }
        if client:
            params["client"] = client

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

        report = response.json()

        monthly_data.append({
            "month": calendar.month_name[month],
            "co2e_kg": report['summary']['total_co2e_kg'],
            "packages": report['summary']['total_items']
        })

    return monthly_data

# Usage
comparison = monthly_comparison(2025, client="AMAZON")
for month_data in comparison:
    print(f"{month_data['month']}: {month_data['co2e_kg']:.2f} kgCO2e ({month_data['packages']} packages)")

Compare Clients

Compare emissions across different clients:

def compare_clients(start_date, end_date):
    """Compare emissions across all clients"""
    # First, get all clients
    clients_response = requests.get(
        "https://api.dcycle.io/v1/logistics/clients",
        headers=headers
    )
    clients = clients_response.json()

    comparison = []
    for client in clients:
        response = requests.get(
            "https://api.dcycle.io/v1/logistics/report",
            headers=headers,
            params={
                "start_date": start_date,
                "end_date": end_date,
                "client": client
            }
        )
        report = response.json()

        comparison.append({
            "client": client,
            "total_co2e_kg": report['summary']['total_co2e_kg'],
            "packages": report['summary']['total_items'],
            "avg_per_package": report['summary']['avg_co2e_per_item']
        })

    # Sort by emissions (highest first)
    comparison.sort(key=lambda x: x['total_co2e_kg'], reverse=True)

    return comparison

# Usage
client_comparison = compare_clients("2025-01-01", "2025-12-31")
for c in client_comparison:
    print(f"{c['client']}: {c['total_co2e_kg']:.2f} kgCO2e ({c['packages']} packages)")

Fleet & Electrification Analysis

Analyze fleet composition and electrification impact:

def fleet_electrification_report(year, client=None):
    """Analyze fleet composition and electrification savings"""
    params = {
        "start_date": f"{year}-01-01",
        "end_date": f"{year}-12-31"
    }
    if client:
        params["client"] = client

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

    report = response.json()

    # Fleet type breakdown
    print("Fleet Composition")
    print("=" * 50)
    for ft in report.get("by_fleet_type", []):
        print(f"  {ft['fleet_type']:30s} {ft['items']:>6} trips  {ft['co2e_kg']:>10.2f} kgCO2e  ({ft['percentage_co2e']}%)")

    # Electrification savings
    savings = report.get("electrification_savings")
    if savings:
        print(f"\nElectrification Savings")
        print("=" * 50)
        print(f"  Electric trips:        {savings['electric_trips']}")
        print(f"  Actual emissions:      {savings['actual_co2e_kg']:.2f} kgCO2e")
        print(f"  Diesel equivalent:     {savings['hypothetical_diesel_co2e_kg']:.2f} kgCO2e")
        print(f"  CO2e avoided:          {savings['avoided_co2e_kg']:.2f} kgCO2e")
        print(f"  Reduction:             {savings['percentage_reduction']}%")
    else:
        print("\nNo electric trips in this period.")

    return report

# Usage
fleet_electrification_report(2025, client="AMAZON")

Data Source Detection

The endpoint automatically detects which data source to use:

Packages (New API)

Used when you have data created via POST /v1/logistics/requests with package tracking.

Aggregates from logistic_packages table
Pre-calculated CO2e per package
data_source: "packages"

Requests (Legacy API)

Used when you have data from the legacy logistics API.

Aggregates from logistic_requests table
CO2e calculated on-the-fly (tkm * emission factor)
data_source: "requests"

ISO 14083 Compliance

This report complies with ISO 14083:2023 standard requirements:

WTW (Well-to-Wheel) Emissions - Includes complete fuel cycle emissions
Transport Mode Breakdown - Clear separation by transport category
Traceability - Each emission is linked to specific packages/shipments
Documented Methodology - Transparent emission factors and calculations
Temporal Aggregation - Reports by defined periods

Export Detailed Report

Queue an async, line-level export emailed as a download link

List Clients

Get available clients for filtering

Get Packages

View individual packages

Create Request

Create new logistics requests

Get Vehicle Types

View available vehicle types and emission factors

List Clients Export Detailed Report

​Generate ISO 14083 Report

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Annual Report

​Monthly Comparison

​Compare Clients

​Fleet & Electrification Analysis

​Data Source Detection

Packages (New API)

Requests (Legacy API)

​ISO 14083 Compliance

​Related Endpoints

Export Detailed Report

List Clients

Get Packages

Create Request

Get Vehicle Types

Generate ISO 14083 Report

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Annual Report

Monthly Comparison

Compare Clients

Fleet & Electrification Analysis

Data Source Detection

ISO 14083 Compliance

Related Endpoints