Transport Tools

Query upstream and downstream transport records — goods transportation with routes, distances, and CO₂e emissions. This covers Scope 3 Category 4 (upstream transportation) and Category 9 (downstream transportation).

`list_transports`

List upstream/downstream transport records with routes, distances, and CO₂e emissions. Use transport_direction to separate inbound raw materials (upstream) from outbound product distribution (downstream). Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`search`	string	No	—	Search by description
`status`	string	No	—	Status filter: `active`, `deleted`
`transport_direction`	string	No	—	Direction: `upstream` or `downstream`
`from_date`	string	No	—	Filter from this date (YYYY-MM-DD)
`to_date`	string	No	—	Filter until this date (YYYY-MM-DD)
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page

Example response:

{
  "items": [
    {
      "id": "a3f1b2c4-...",
      "name": "Raw materials from supplier",
      "transport_date": "2024-06-15",
      "transport_direction": "upstream",
      "transport_frequency": "once",
      "quantity_transported": 2500.0,
      "supplier": "Acme Logistics",
      "status": "active",
      "co2e": 145.3,
      "unit": {
        "id": "61743a63-...",
        "name": "kilogram_(kg)",
        "type": "weight"
      },
      "sections": [
        {
          "id": "sec-1a2b3c4d-...",
          "part": 1,
          "origin": "Barcelona, Spain",
          "origin_geocode": {
            "country_code": "ES",
            "place_id": "ChIJ5TCOcRaYpBIRCmZHTz37sEQ",
            "address_formatted": "Barcelona, Spain",
            "latitude": 41.3874,
            "longitude": 2.1686
          },
          "destination": "Madrid, Spain",
          "destination_geocode": {
            "country_code": "ES",
            "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ",
            "address_formatted": "Madrid, Spain",
            "latitude": 40.4168,
            "longitude": -3.7038
          },
          "transport_type": "road",
          "electric": false,
          "refrigerated": false,
          "kms": 620.0,
          "kms_source": "google_maps",
          "status": "active",
          "reference_product": null,
          "emissions": [
            { "value": 145.3, "gas": "co2e", "unit_name": "kgCO2e" }
          ]
        }
      ],
      "created_at": "2024-06-10T08:00:00Z"
    }
  ],
  "total": 156,
  "page": 1,
  "size": 50,
  "pages": 4
}

Key response fields:

Field	Description
`transport_direction`	`upstream` (suppliers → you) or `downstream` (you → customers)
`transport_frequency`	`once`, `weekly`, or `monthly`
`quantity_transported`	Amount transported in the unit specified by `unit.name`
`supplier`	Supplier or carrier name
`co2e`	Total CO₂e emissions in kg across all sections
`sections`	Route legs with origin/destination, geocodes, distance (`kms`), and per-section `emissions`
`sections[].transport_type`	`road`, `air`, `rail`, `maritime`, or `do_not_know`
`sections[].kms`	Calculated or user-provided distance in kilometers
`sections[].origin_geocode`	Geocoded origin with lat/lon and country code (null if not geocoded)

Example prompts:

"Show our upstream transport records for 2024"
"List downstream transports to Madrid"
"What are our transport emissions from Barcelona routes?"
"Show all transports from supplier Acme"
"List one-time transports in Q1 2025"

Write Operations

`create_transport`

Create a transport (shipment) record for Scope 3 upstream or downstream transportation. A transport consists of a route-level record (date, quantity, direction) and one or more sections (legs), each with its own transport mode, origin/destination, and distance. CO₂e is calculated asynchronously after creation — the response will initially show co2e as null. Route parameters:

Parameter	Type	Required	Default	Description
`transport_date`	string	Yes	—	Date of shipment (`YYYY-MM-DD`)
`quantity_transported`	number	Yes	—	Weight of goods (must be > 0)
`unit_id`	string	Yes	—	UUID of the weight unit (e.g. kg, tonne)
`sections`	array	Yes	—	List of transport sections (at least one)
`name`	string	No	—	Description or label (e.g. “Raw materials from supplier A”)
`supplier`	string	No	—	Supplier or carrier name
`transport_direction`	string	No	—	`upstream` (Scope 3 Cat 4) or `downstream` (Scope 3 Cat 9)
`organization_id`	string	No	default org	Organization UUID

Section parameters (each item in sections):

Parameter	Type	Required	Default	Description
`transport_type`	string	Yes	—	`road`, `rail`, `air`, `maritime`, or `do_not_know`
`electric`	boolean	Yes	—	Whether the vehicle is electric-powered
`refrigerated`	boolean	Yes	—	Whether the transport is refrigerated
`distance_manual`	boolean	Yes	—	`true` = provide `kms_manual`; `false` = auto-calculate from origin/destination
`origin`	string	No	—	Origin address (e.g. “Barcelona, Spain”). Required when `distance_manual=false`
`destination`	string	No	—	Destination address. Required when `distance_manual=false`
`kms_manual`	number	No	—	Manual distance in km (required when `distance_manual=true`, must be > 0)
`travel_method`	string	No	—	For road: `truck`, `car`, `motorbike`, `bicycle`, `electric_kick_scooter`
`detail`	string	No	—	Vehicle size/distance detail for emission factor selection

Each section requires either origin + destination (for automatic distance calculation via geocoding) or kms_manual with distance_manual=true (for known distances). You can mix modes in a multi-section route — e.g. road from factory to port, then maritime to destination port.

CO₂e emissions are calculated in the background after creation. The initial response will show co2e: null. Call list_transports after a few seconds to see the calculated value.

Example response:

{
  "id": "a3f1b2c4-...",
  "name": "Raw materials from supplier A",
  "transport_date": "2025-06-15",
  "transport_direction": "upstream",
  "transport_frequency": "once",
  "quantity_transported": 1500.0,
  "status": "active",
  "co2e": null,
  "sections": [
    {
      "id": "sec-1a2b...",
      "part": 1,
      "transport_type": "road",
      "origin": "Barcelona, Spain",
      "destination": "Madrid, Spain",
      "electric": false,
      "refrigerated": false,
      "distance_manual": false,
      "status": "pending"
    }
  ],
  "created_at": "2025-06-15T10:30:00Z"
}

Example prompts:

"Log a truck shipment of 2000 kg from Barcelona to Madrid, upstream"
"Create a rail transport of 500 tonnes from Hamburg to Munich"
"Record a maritime shipment, 10000 kg, 8500 km manual distance, downstream"
"Add a multi-leg transport: truck Madrid→Valencia port, then ship to Genoa"

Common errors:

Error	Cause
422: “sections must contain at least one section”	Empty sections array
422: “unit_id not found”	Invalid weight unit UUID
422: “quantity_transported must be > 0”	Zero or negative quantity

`update_transport`

Update an existing transport (shipment) record. This is a full replacement — you must re-send all sections, even if only changing top-level fields like name or date.

Unlike other update tools, update_transport requires the full sections array every time. To modify a transport: first retrieve it with list_transports, then change the fields you need, and pass the complete sections back.

Parameters:

Parameter	Type	Required	Default	Description
`transport_id`	string	Yes	—	UUID of the transport. Use `list_transports` to find it
`sections`	array	Yes	—	Full list of transport sections (same format as `create_transport`)
`transport_date`	string	No	—	New shipment date (`YYYY-MM-DD`)
`quantity_transported`	number	No	—	New weight of goods (> 0)
`unit_id`	string	No	—	New weight unit UUID
`name`	string	No	—	New description or label
`supplier`	string	No	—	New supplier name
`transport_frequency`	string	No	—	`once`, `monthly`, or `weekly`
`organization_id`	string	No	default org	Organization UUID

Example prompts:

"Update transport abc-123 to use rail instead of road"
"Change the quantity to 3000 kg on transport xyz"
"Fix the supplier name on transport abc to 'Acme Logistics'"

Common errors:

Error	Cause
404: “Transport not found”	Invalid transport UUID
422: “sections must contain at least one section”	Empty sections array

Workflows

Querying transport records

List transports — list_transports filtered by direction, date range, or search
View emissions — get_greenhouse_gas_emissions with category=transport_distribution_upstream or category=transport_distribution_downstream for aggregated totals
View logistics — list_logistics_requests for GLEC-framework logistics calculations

Logging a new shipment

Find weight unit — Use list_facilities or get_organization_metrics to find the unit_id for kg or tonne
Create transport — create_transport with route details and at least one section
Verify — list_transports to confirm it appears and check CO₂e calculation status

Logistics

GLEC-framework logistics calculations

Emissions

Aggregated Scope 3 transport emissions

API Reference

REST API endpoints for transport records

​Transport Tools

​list_transports

​Write Operations

​create_transport

​update_transport

​Workflows

​Querying transport records

​Logging a new shipment

​Related

Logistics

Emissions

API Reference

Transport Tools

`list_transports`

Write Operations

`create_transport`

`update_transport`

Workflows

Querying transport records

Logging a new shipment

Related