Skip to main content
GET
/
api
/
v1
/
logistics
/
clients
/
report
Generate Report
const options = {
  method: 'GET',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'x-user-id': '<x-user-id>'
  }
};

fetch('https://api.dcycle.io/api/v1/logistics/clients/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_co2e": 123,
    "total_distance": 123,
    "total_load": 123,
    "total_shipments": 123,
    "avg_co2e_per_shipment": 123,
    "avg_distance_per_shipment": 123
  },
  "by_transport_type": [
    {
      "toc": "<string>",
      "shipments": 123,
      "co2e": 123,
      "distance": 123,
      "percentage_co2e": 123
    }
  ],
  "methodology": "<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.

​
Generate ISO 14083 Report

Generate a complete logistics emissions report for a client following ISO 14083 methodology. Includes aggregated KPIs and breakdowns by transport type.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
​
x-user-id
string
required
Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Query Parameters

​
client
string
required
Exact client name (case-sensitive)Example: "Correos Express"
​
start_date
string
required
Period start date (format: YYYY-MM-DD)Example: "2024-01-01"
​
end_date
string
required
Period end date (format: YYYY-MM-DD)Example: "2024-12-31"

​
Response

​
client
string
Client name
​
period
object
​
summary
object
​
by_transport_type
array
Breakdown by transport type
​
methodology
string
Methodology used (always “ISO 14083”)

​
Example

curl -X GET "https://api.dcycle.io/api/v1/logistics/clients/report?client=Correos+Express&start_date=2024-01-01&end_date=2024-12-31" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

​
Successful Response

{
  "client": "Correos Express",
  "period": {
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  },
  "summary": {
    "total_co2e": 125430.75,
    "total_distance": 456789.5,
    "total_load": 3500000,
    "total_shipments": 15234,
    "avg_co2e_per_shipment": 8.23,
    "avg_distance_per_shipment": 29.97
  },
  "by_transport_type": [
    {
      "toc": "van_diesel",
      "shipments": 8500,
      "co2e": 72000.50,
      "distance": 255000.0,
      "percentage_co2e": 57.4
    },
    {
      "toc": "truck_diesel",
      "shipments": 4200,
      "co2e": 38430.25,
      "distance": 156789.5,
      "percentage_co2e": 30.6
    },
    {
      "toc": "van_electric",
      "shipments": 2534,
      "co2e": 15000.00,
      "distance": 45000.0,
      "percentage_co2e": 12.0
    }
  ],
  "methodology": "ISO 14083"
}

​
Use Cases

​
Annual Report

Generate the complete annual report for audits: 
def generate_annual_report(client, year):
    """Generate annual ISO 14083 report"""
    start_date = f"{year}-01-01"
    end_date = f"{year}-12-31"

    report = get_report(client, start_date, end_date)

    # Save report
    filename = f"report_{client}_{year}_ISO14083.json"
    with open(filename, 'w') as f:
        json.dump(report, f, indent=2)

    return report

# Example
annual_report = generate_annual_report("Correos Express", 2024)
print(f"Annual emissions: {annual_report['summary']['total_co2e']/1000:.2f} tons CO2e")

​
Monthly Comparison

Compare emissions month by month: 
import calendar

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

    for month in range(1, 13):
        # Calculate last day of month
        last_day = calendar.monthrange(year, month)[1]

        start_date = f"{year}-{month:02d}-01"
        end_date = f"{year}-{month:02d}-{last_day}"

        report = get_report(client, start_date, end_date)

        monthly_data.append({
            "month": calendar.month_name[month],
            "co2e": report['summary']['total_co2e'],
            "shipments": report['summary']['total_shipments']
        })

    return monthly_data

# Usage
comparison = monthly_comparison("Correos Express", 2024)
for month_data in comparison:
    print(f"{month_data['month']}: {month_data['co2e']:.2f} kg CO2e ({month_data['shipments']} shipments)")

​
Sustainability Dashboard

Extract KPIs for a dashboard: 
def get_sustainability_kpis(client, start_date, end_date):
    """Extract key KPIs for dashboard"""
    report = get_report(client, start_date, end_date)

    kpis = {
        "total_emissions_tons": report['summary']['total_co2e'] / 1000,
        "avg_emissions_per_shipment": report['summary']['avg_co2e_per_shipment'],
        "total_shipments": report['summary']['total_shipments'],
        "total_distance_km": report['summary']['total_distance'],
        "most_used_transport": max(
            report['by_transport_type'],
            key=lambda x: x['shipments']
        )['toc'],
        "greenest_transport": min(
            report['by_transport_type'],
            key=lambda x: x['co2e'] / x['shipments']
        )['toc']
    }

    return kpis

​
Common Errors

​
404 Not Found - Client Not Found

{
  "detail": "No data found for client 'Correos Express'",
  "code": "CLIENT_NOT_FOUND"
}
Cause: The client name doesn’t exist or has a typo Solution:
  1. Use the Get Clients endpoint to see exact names
  2. Verify you wrote the name exactly the same (case-sensitive)

​
400 Bad Request - Invalid Date Format

{
  "detail": "Invalid date format. Use YYYY-MM-DD",
  "code": "INVALID_DATE_FORMAT"
}
Solution: Use the YYYY-MM-DD format (for example: "2024-11-20")

​
400 Bad Request - Date Range Too Large

{
  "detail": "Date range cannot exceed 1 year",
  "code": "DATE_RANGE_TOO_LARGE"
}
Solution: Divide the period into smaller ranges (maximum 1 year per request)

​
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 vehicle type ✅ Traceability - Each emission is linked to a specific shipment ✅ Documented Methodology - Transparent emission factors and calculations ✅ Temporal Aggregation - Reports by defined periods

Get Clients

List available clients

Upload CSV

Upload bulk shipments

Calculate Shipment

Individual calculation

Get TOCs

List transport types