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

# Logistics Tools

> MCP tools for querying logistics shipments, hubs, clients, and ISO 14083 emissions reports

# Logistics Tools

Query logistics and shipping data — shipment requests with ISO 14083 emission calculations, distribution hubs, client breakdowns, and aggregated GLEC reports. Each shipment has origin, destination, distance, load, TOC (Type of Carrier), and calculated kgCO2e emissions.

## `list_logistics_requests`

List logistics/shipping requests with emission calculations.

**Parameters:**

| Parameter         | Type    | Required | Default     | Description       |
| ----------------- | ------- | -------- | ----------- | ----------------- |
| `organization_id` | string  | No       | default org | Organization UUID |
| `page`            | integer | No       | 1           | Page number       |
| `size`            | integer | No       | 50          | Results per page  |

<Warning>
  `kgco2e` and `emission_intensity` may be null if emission calculations are still pending or have failed. If all returned records show null emissions, the calculation pipeline may not be running — check `list_processing_jobs` for failures.
</Warning>

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "b652bf60-...",
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "distance_km": 600.0,
      "load": 121.0,
      "load_unit": "kg",
      "toc": "generic_average_road",
      "kgco2e": 11.13,
      "emission_intensity": 153.318,
      "tkm": 72.6,
      "client": "Acme Corp",
      "shipment_date": "2025-11-25",
      "movement_id": "MOV-2024-001234",
      "movement_stretch": "last_mile",
      "movement_stage": "delivery",
      "vehicle_license_plate": "1234-ABC",
      "subcontractor": true,
      "subcontractor_type": "fis",
      "hub_id": "HUB-MAD-001",
      "status": "active",
      "cleaning": false,
      "error_messages": null,
      "estimated_data": null,
      "file_name": "shipments_q1.csv",
      "created_at": "2025-11-25T10:00:00"
    }
  ],
  "total": 57534,
  "page": 1,
  "size": 50
}
```

**Key response fields:**

| Field                | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| `toc`                | Type of Carrier — vehicle type identifier (e.g. `van_diesel`, `artic_truck_diesel`) |
| `tkm`                | Tonne-kilometres (load in tonnes × distance in km)                                  |
| `kgco2e`             | Kilograms of CO2 equivalent emitted (null if pending)                               |
| `emission_intensity` | gCO2e per tonne-kilometre                                                           |
| `client`             | Client name for the shipment                                                        |
| `movement_id`        | External reference ID for traceability                                              |
| `subcontractor_type` | `fis` (Fully Integrated) or `nis` (Non-Integrated) per ISO 14083                    |
| `error_messages`     | Calculation errors (null if successful)                                             |

## `list_logistics_clients`

List unique client names associated with the organization's logistics operations.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description            |
| ----------------- | ------ | -------- | ----------- | ---------------------- |
| `organization_id` | string | No       | default org | Organization UUID      |
| `project_id`      | string | No       | —           | Filter by project UUID |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
["ACME Spain", "Correos Express", "MRW", "Seur", "DHL"]
```

<Note>
  Returns a flat list of client name strings. The organization's own company name is always included in the list.
</Note>

## `list_logistics_hubs`

List distribution hubs (warehouses, depots) used in logistics operations.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description                          |
| ----------------- | ------ | -------- | ----------- | ------------------------------------ |
| `organization_id` | string | No       | default org | Organization UUID                    |
| `name`            | string | No       | —           | Filter by hub name (partial match)   |
| `type`            | string | No       | —           | Hub type: `owned` or `subcontracted` |
| `category`        | string | No       | —           | Hub category filter                  |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "hub-1a2b3c4d-...",
      "name": "Madrid Central Warehouse",
      "address": "Calle de la Industria 45, Madrid",
      "country": "ES",
      "type": "owned",
      "category": "warehouse",
      "status": "active",
      "supercharger": false,
      "facility_id": "fac-5e6f7a8b-...",
      "co2e": 245.3,
      "created_at": "2024-06-15T09:00:00",
      "updated_at": "2025-03-10T14:00:00"
    }
  ],
  "total": 5
}
```

**Key response fields:**

| Field          | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `type`         | `owned` (company-operated) or `subcontracted` (third-party) |
| `facility_id`  | Linked facility UUID (only for owned hubs)                  |
| `co2e`         | CO2 equivalent emissions from the linked facility           |
| `supercharger` | Whether the hub is a supercharger station                   |

## `get_logistics_report`

Get an aggregated ISO 14083 (GLEC) logistics emissions report with optional date range and client filters.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description             |
| ----------------- | ------ | -------- | ----------- | ----------------------- |
| `organization_id` | string | No       | default org | Organization UUID       |
| `start_date`      | string | No       | —           | Start date (YYYY-MM-DD) |
| `end_date`        | string | No       | —           | End date (YYYY-MM-DD)   |
| `client_name`     | string | No       | —           | Filter by client name   |
| `project_id`      | string | No       | —           | Filter by project UUID  |

<Note>
  The report shape varies by filter. Without a client filter, it returns full **scope 1/2/3 breakdowns** with SQAS/ISO 14083 subcontractor splits. With a specific client filter, it returns per-client TOC and company emission breakdowns (no scope keys).
</Note>

**Example response (company-wide):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "scope_1": { "total_emissions": 1250.5, ... },
  "scope_2": { "total_emissions": 890.2, ... },
  "scope_3": {
    "total_emissions": 45230.8,
    "wtw_subcontracted_emissions_by_type": { "fis": 12500.0, "nis": 32730.8 }
  },
  "tocs_info": [...],
  "hocs_info": [...],
  "transport_mode_info": [...]
}
```

## `get_logistics_summary`

Get a high-level summary of logistics operations — entity counts and last update timestamps.

**Parameters:**

| Parameter         | Type   | Required | Default     | Description            |
| ----------------- | ------ | -------- | ----------- | ---------------------- |
| `organization_id` | string | No       | default org | Organization UUID      |
| `project_id`      | string | No       | —           | Filter by project UUID |

**Example response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "shipments": {
    "count": 57534,
    "last_updated": "2025-06-28T16:30:00"
  },
  "consumptions": {
    "count": 1245,
    "last_updated": "2025-06-25T09:15:00"
  },
  "hubs": {
    "count": 12,
    "last_updated": "2025-03-10T14:00:00"
  }
}
```

**Key response fields:**

| Field          | Description                             |
| -------------- | --------------------------------------- |
| `shipments`    | Transport request count and last update |
| `consumptions` | Fuel recharge/consumption record count  |
| `hubs`         | Distribution hub count                  |

**Example prompts:**

```
"Show our recent shipping requests"
"What are the top routes by emissions?"
"How many logistics requests do we have?"
"List our logistics clients"
"Show me our warehouses and depots"
"Generate a logistics emissions report for Acme Corp in 2024"
"What's the TOC and HOC summary for our logistics?"
"Which shipments have pending emission calculations?"
```

## Workflow

1. **Get overview** — `get_logistics_summary` for entity counts and freshness
2. **Browse shipments** — `list_logistics_requests` to see individual shipment data with emissions
3. **Understand clients** — `list_logistics_clients` to see which clients generate shipments
4. **Check hubs** — `list_logistics_hubs` to see distribution infrastructure
5. **Generate report** — `get_logistics_report` for the full ISO 14083 GLEC emissions breakdown

## Related

<CardGroup cols={2}>
  <Card title="Emissions" icon="smog" href="/mcp/emissions">
    GHG emissions including logistics (Scope 3)
  </Card>

  <Card title="Facilities" icon="building" href="/mcp/facilities">
    Facilities linked to owned logistics hubs
  </Card>

  <Card title="Processing Jobs" icon="gears" href="/mcp/processing-jobs">
    Check calculation pipeline status for pending emissions
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/logistics/overview">
    REST API endpoints for logistics
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/logistics">
    Manage logistics from the command line
  </Card>
</CardGroup>