Skip to main content
GET
/
v1
/
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));
{
  "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

​
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

​
start_date
string
required
Period start date (format: YYYY-MM-DD)Example: 2025-01-01
​
end_date
string
required
Period end date (format: YYYY-MM-DD)Example: 2025-12-31
​
client
string
Filter by client identifier (optional)Example: AMAZON

​
Response

​
client
string
Client filter applied (null if not filtered)
​
period
object
​
summary
object
​
by_category
array
Breakdown by transport category
​
by_fleet_type
array
Breakdown by fleet type — cross-tabulation of ownership (own vs third-party) and energy type (conventional, electrified, renewable)
​
electrification_savings
object
Electrification savings analysis comparing actual electric trip emissions vs hypothetical diesel equivalent. null when no electric trips exist in the period.
​
data_source
string
Source of data: packages (new API) or requests (legacy API)
​
methodology
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}"

​
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

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