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

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.

Example response:

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

["ACME Spain", "Correos Express", "MRW", "Seur", "DHL"]

Returns a flat list of client name strings. The organization’s own company name is always included in the list.

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

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

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

Example response (company-wide):

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

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

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

Emissions

GHG emissions including logistics (Scope 3)

Facilities

Facilities linked to owned logistics hubs

Processing Jobs

Check calculation pipeline status for pending emissions

API Reference

REST API endpoints for logistics

CLI

Manage logistics from the command line

Getting Started

Tools Reference

Reference Data

Logistics Tools

Logistics Tools

`list_logistics_requests`

`list_logistics_clients`

`list_logistics_hubs`

`get_logistics_report`

`get_logistics_summary`

Workflow

Emissions

Facilities

Processing Jobs

API Reference

CLI

​Logistics Tools

​list_logistics_requests

​list_logistics_clients

​list_logistics_hubs

​get_logistics_report

​get_logistics_summary

​Workflow

​Related

Emissions

Facilities

Processing Jobs

API Reference

CLI

Logistics Tools

`list_logistics_requests`

`list_logistics_clients`

`list_logistics_hubs`

`get_logistics_report`

`get_logistics_summary`

Workflow

Related