Generate Report

Generate a complete ISO 14083 report for a client in a specific period

GET /api/v1/logistics/clients/report

Generate Report

JavaScript

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

200

{
  "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>"
}

Generate ISO 14083 Report

Legacy API. This page documents the previous version of the API. For new integrations use Generate Report instead.

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 authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

x-user-id · string · required

Your user UUID

Example: 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

Show properties

start_date · string

Start date

end_date · string

End date

summary · object

Show properties

total_co2e · number

Total emissions in kg CO2e

total_distance · number

Total distance in km

total_load · number

Total transported load

total_shipments · integer

Total number of shipments

avg_co2e_per_shipment · number

Average CO2e per shipment

avg_distance_per_shipment · number

Average distance per shipment

by_transport_type · array

Breakdown by transport type

Show properties

toc · string

Transport type

shipments · integer

Number of shipments

co2e · number

Emissions in kg

distance · number

Distance in km

percentage_co2e · number

Percentage of total emissions

methodology · string

Methodology used (always “ISO 14083”)

Example

cURL

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

Cause: No data found for client ‘Correos Express’

{
  "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

Cause: Invalid date format. Use YYYY-MM-DD

{
  "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

Cause: Date range cannot exceed 1 year

{
  "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

Related Endpoints

Get Clients

List available clients

Upload CSV

Upload bulk shipments

Calculate Shipment

Individual calculation

Get TOCs

List transport types