> ## 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.

# Calculate Shipment

> Calculate CO2e emissions for an individual shipment following ISO 14083 standard

# Calculate Shipment Emissions

<Warning>
  **Legacy API.** This page documents the previous version of the API. This particular
  operation has no documented equivalent in the current API yet, so this remains the
  documented way to do it. Prefer the current API for everything it already covers.
</Warning>

Calculate CO2 equivalent (CO2e) emissions for a freight shipment. This endpoint follows ISO 14083 methodology for calculating transport emissions.

<Note>
  This endpoint calculates emissions but **does not persist** the shipment in the database. For bulk uploads that persist, use the [CSV upload endpoint](/api-reference/legacy/logistics/upload-csv).
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `ff4adcc7-8172-45fe-9cf1-e90a6de53aa9`
</ParamField>

<ParamField header="x-user-id" type="string" required>
  Your user UUID

  **Example:** `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
</ParamField>

### Body Parameters

<ParamField body="origin" type="string" required>
  Origin location of the shipment (city and country)

  **Example:** `"Madrid, Spain"`
</ParamField>

<ParamField body="destination" type="string" required>
  Destination location of the shipment

  **Example:** `"Barcelona, Spain"`
</ParamField>

<ParamField body="toc" type="string" required>
  Transport type (Transport Operation Category)

  **Possible values:**

  * `van_diesel` - Diesel van
  * `van_electric` - Electric van
  * `truck_diesel` - Diesel truck
  * `truck_articulated` - Articulated truck
  * `rail_freight` - Freight train
  * `air_freight` - Cargo airplane
  * `sea_container` - Container ship

  Retrieve available options from [`GET /v1/logistics/tocs`](/api-reference/logistics/list-tocs)
</ParamField>

<ParamField body="load" type="number" required>
  Transported load quantity

  **Example:** `1000`
</ParamField>

<ParamField body="load_unit" type="string" required>
  Unit of measurement for the load

  **Possible values:** `kg`, `ton`, `m3`, `pallet`
</ParamField>

<ParamField body="year" type="integer">
  Shipment year (default: current year)

  **Example:** `2024`
</ParamField>

## Response

<ResponseField name="co2e" type="number">
  Total CO2 equivalent emissions in kilograms
</ResponseField>

<ResponseField name="distance_km" type="number">
  Calculated shipment distance in kilometers
</ResponseField>

<ResponseField name="toc" type="string">
  Transport type used
</ResponseField>

<ResponseField name="load" type="number">
  Transported load
</ResponseField>

<ResponseField name="load_unit" type="string">
  Load unit of measurement
</ResponseField>

<ResponseField name="origin" type="string">
  Shipment origin
</ResponseField>

<ResponseField name="destination" type="string">
  Shipment destination
</ResponseField>

<ResponseField name="year" type="integer">
  Shipment year
</ResponseField>

<ResponseField name="emission_factor" type="number">
  Emission factor used (kg CO2e per ton-km)
</ResponseField>

<ResponseField name="methodology" type="string">
  Methodology used for calculation (always "ISO 14083")
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/api/v1/logistics/shipment" \
    -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "x-user-id: ${DCYCLE_USER_ID}" \
    -H "Content-Type: application/json" \
    -d '{
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "toc": "van_diesel",
      "load": 1000,
      "load_unit": "kg",
      "year": 2024
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  api_key = os.getenv("DCYCLE_API_KEY")
  org_id = os.getenv("DCYCLE_ORG_ID")

  headers = {
      "Authorization": f"Bearer {api_key}",
      "x-organization-id": org_id,
      "x-user-id": user_id,
      "Content-Type": "application/json"
  }

  payload = {
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "toc": "van_diesel",
      "load": 1000,
      "load_unit": "kg",
      "year": 2024
  }

  response = requests.post(
      "https://api.dcycle.io/api/v1/logistics/shipment",
      headers=headers,
      json=payload
  )

  result = response.json()
  print(f"CO2e: {result['co2e']} kg")
  print(f"Distance: {result['distance_km']} km")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const apiKey = process.env.DCYCLE_API_KEY;
  const orgId = process.env.DCYCLE_ORG_ID;

  const headers = {
    'Authorization': `Bearer ${apiKey}`,
    'x-organization-id': orgId,
    'x-user-id': userId,
    'Content-Type': 'application/json'
  };

  const payload = {
    origin: "Madrid, Spain",
    destination: "Barcelona, Spain",
    toc: "van_diesel",
    load: 1000,
    load_unit: "kg",
    year: 2024
  };

  axios.post(
    'https://api.dcycle.io/api/v1/logistics/shipment',
    payload,
    { headers }
  )
  .then(response => {
    console.log(`CO2e: ${response.data.co2e} kg`);
    console.log(`Distance: ${response.data.distance_km} km`);
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "co2e": 245.5,
  "distance_km": 620.0,
  "toc": "van_diesel",
  "load": 1000,
  "load_unit": "kg",
  "origin": "Madrid, Spain",
  "destination": "Barcelona, Spain",
  "year": 2024,
  "emission_factor": 0.000396,
  "methodology": "ISO 14083"
}
```

## Common Errors

### 400 Bad Request

**Cause:** Missing required parameters or incorrect format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Field required",
  "code": "VALIDATION_ERROR",
  "field": "origin"
}
```

**Solution:** Verify that all required fields are present and correctly formatted.

### 422 Unprocessable Entity

**Cause:** Invalid transport type (toc)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid transport type",
  "code": "INVALID_TOC"
}
```

**Solution:** Use one of the valid values for `toc`: `van_diesel`, `van_electric`, `truck_diesel`, etc.

## Use Cases

### Quick Estimation

Use it to provide instant estimates to users before confirming a shipment:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Show estimate to user before confirming
estimate = calculate_shipment(origin, destination, load)
print(f"This shipment will generate {estimate['co2e']} kg of CO2e")
```

### Comparing Options

Compare different transport modes:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
modes = ["van_diesel", "van_electric", "rail_freight"]
for mode in modes:
    result = calculate_shipment(origin, destination, load, toc=mode)
    print(f"{mode}: {result['co2e']} kg CO2e")
```

## ISO 14083 Methodology

This endpoint implements the ISO 14083:2023 standard for quantification and reporting of GHG emissions in transport operations.

**Basic formula:**

```
CO2e = Distance (km) × Load (ton) × Emission Factor (kg CO2e/ton-km)
```

Emission factors are regularly updated based on:

* GLEC Framework database
* National country factors
* Vehicle manufacturer data

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Upload CSV" icon="upload" href="/api-reference/legacy/logistics/upload-csv">
    Bulk upload shipments
  </Card>

  <Card title="Get Clients" icon="list" href="/api-reference/legacy/logistics/get-clients">
    List your logistics clients
  </Card>

  <Card title="Get Report" icon="chart-line" href="/api-reference/legacy/logistics/get-report">
    Generate ISO 14083 report
  </Card>

  <Card title="Get TOCs" icon="truck" href="/api-reference/legacy/logistics/get-tocs">
    List available transport types
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.