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

`create_logistics_request`

Create a new shipping request for ISO 14083 emission tracking. Uses POST /v2/logistics/requests with one record: the leg is written at once and its distance and emissions are calculated by an ingest job. The tool returns the job (status: processing) and the idempotency_key it sent, not the leg. Parameters:

Parameter	Type	Required	Description
`category`	string	Conditional	Transport category: `road`, `rail`, `maritime`, or `air`. Required if `toc` not set
`toc`	string	Conditional	Vehicle type ID (e.g. `van_diesel`). Overrides category
`origin`	string	No	Origin address (geocoded to compute distance)
`destination`	string	No	Destination address (geocoded to compute distance)
`distance_km`	number	No	Direct distance in km (overrides geocoding, must be > 0)
`origin_country`	string	No	ISO country code for origin (default `GLO`)
`load`	number	No	Shipment load amount (must be > 0)
`load_unit`	string	No	Load unit: `kg`, `ton`, `pallets`, `teu`, or `feu`
`load_factor`	number	No	Load utilization factor (`0 < value <= 1.0`)
`year`	integer	No	Year for emission factor lookup
`cleaning`	boolean	No	Include cleaning emissions
`client_name`	string	No	Client/customer name
`shipment_date`	string	No	Shipment date (YYYY-MM-DD)
`movement_id`	string	No	External shipment tracking ID
`movement_stretch`	string	No	Stretch label (e.g. `first_mile`, `last_mile`)
`movement_stage`	string	No	Stage label (e.g. `delivery`)
`vehicle_license_plate`	string	No	License plate of transport vehicle
`subcontractor`	boolean	No	Whether transport is subcontracted
`subcontractor_type`	string	No	Subcontractor type: `fis` or `nis`
`tkm`	number	No	Tonne-km (bypasses load/distance if provided)
`hub_id`	string	No	UUID of a logistics hub
`idempotency_key`	string	No	Only to retry a call that failed without an answer: the key of that call, so the backend returns its job instead of writing again. A fresh key is generated otherwise
`organization_id`	string	No	Organization UUID (uses default if not set)

Either category or toc must be provided. Poll get_ingest_job with the returned job id until its status is completed, completed_with_errors or failed, then read the leg and its emissions with list_logistics_requests.

Example prompts:

"Create a road shipment from Madrid to Barcelona with 500 kg"
"Add a maritime logistics request for 2 TEU from Valencia to Rotterdam"
"Create a logistics request using van_diesel for 150 km"

`get_ingest_job`

Status and counters of a bulk ingest job, such as the one create_logistics_request returns (GET /v2/ingest-jobs/{id}). Parameters:

Parameter	Type	Required	Description
`job_id`	string	Yes	UUID of the job returned by the write tool
`include_failed_items`	boolean	No	Also return the records that failed and their reason (first 50)
`organization_id`	string	No	Organization UUID (uses default if not set)

The job’s status is processing while it runs, then completed, completed_with_errors or failed; counts has submitted, succeeded and failed.

Workflow

Get overview — get_logistics_summary for entity counts and freshness
Create shipments — create_logistics_request to add new shipping records, then get_ingest_job until its job finishes
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

`list_logistics_requests`

`list_logistics_clients`

`list_logistics_hubs`

`get_logistics_report`

`get_logistics_summary`

`create_logistics_request`

`get_ingest_job`

Workflow

Emissions

Facilities

Processing Jobs

API Reference

CLI

​list_logistics_requests

​list_logistics_clients

​list_logistics_hubs

​get_logistics_report

​get_logistics_summary

​create_logistics_request

​get_ingest_job

​Workflow

​Related

Emissions

Facilities

Processing Jobs

API Reference

CLI

`list_logistics_requests`

`list_logistics_clients`

`list_logistics_hubs`

`get_logistics_report`

`get_logistics_summary`

`create_logistics_request`

`get_ingest_job`

Workflow

Related