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

# Transport Tools

> MCP tools for querying upstream and downstream transport records and emissions (Scope 3)

# 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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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"
```

## Workflow

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

## Related

<CardGroup cols={2}>
  <Card title="Logistics" icon="truck" href="/mcp/logistics">
    GLEC-framework logistics calculations
  </Card>

  <Card title="Emissions" icon="smog" href="/mcp/emissions">
    Aggregated Scope 3 transport emissions
  </Card>

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