# Train: ADEME 🇫🇷

## High‑Level Description

* ADEME (French Agency for Ecological Transition) provides a comprehensive methodology to assess the environmental impacts of train travel.
* Coverage spans the full lifecycle (vehicle and infrastructure production, operations, maintenance, and end‑of‑life).
* Key drivers include train type (high‑speed, mainline, local/express), traction/fuel (electricity vs. diesel), grid mix, and infrastructure allocation.
* Intended users: railway operators, policymakers, aggregators, and product teams who need transparent, audit‑ready train CO₂e estimates.

***

## Sample API Requests

### A. Without audit mode (for pre-booking/quotes)

```json
{
  "expand": ["items"],
  "items": [
    {
      "audit": false,
      "type": "train",
      "external_reference": "test_2",
      "origin": "BER",
      "destination": "FRA",
      "number_of_travelers": 3,
      "train_type": "mainline",
      "fuel_type": "diesel",
      "methodology": "ADEME"
    }
  ]
}
```

### B. With audit mode (for finalized/post-booking calculations)

```json
{
  "expand": ["items"],
  "audit_for": "<Auditable Entity ID>",
  "items": [
    {
      "audit": true,
      "type": "train",
      "external_reference": "test_2",
      "origin": "BER",
      "destination": "FRA",
      "number_of_travelers": 3,
      "train_type": "mainline",
      "fuel_type": "diesel",
      "methodology": "ADEME"
    }
  ]
}
```

> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.

***

## API Request Items

* `"type": "train"` **(required)**
* `"methodology": "ADEME"` **(required)**
* `"external_reference"`: A unique identifier linking results to the requested item. Max length: 128 chars.
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"origin"`: Origin location (see **Origin/Destination Formats** below).
* `"destination"`: Destination location (see **Origin/Destination Formats** below).
* `"distance_in_km"`: If provided, this value is **prioritized** over `origin`/`destination`. If both are present, `distance_in_km` is used.
* `"train_type"`: One of `high_speed`, `mainline`, `local_express`. **Default:** `local_express`.
* `"fuel_type"`: One of `diesel`, `electricity`. **Default:** `diesel`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.

### Default Values

```json
{
  "fuel_type": "diesel",
  "train_type": "local_express",
  "number_of_travelers": 1
}
```

***

## Origin/Destination Formats (Enriched)

SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally:

* **Addresses:** Use the *Post* standard.
* **Airports:** Use IATA/ICAO code (regex: `^[A-Z]{3,4}$`, e.g., `"MUC"`).
* **Ports/Trade locations:** Use UN/LOCODE (regex: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`).
* **Coordinates:** Pass latitude/longitude (regex: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).

**UIC and Provider Codes for Trains**

* UIC code is also a valid format for trains. If the value is not valid, the system will **fallback to general, non‑journey‑specific emission data**.
* When you want to use a UIC or provider code, use the following format:
  * `<provider>:<uic_code>` (e.g., `sncf:FRAAA`)
* **Possible provider prefixes:**
  * `uic`
  * `uic8_sncf`
  * `sncf`
  * `sncf_tvs`
  * `entur`
  * `db`
  * `busbud`
  * `distribusion`
  * `flixbus`
  * `cff`
  * `leoexpress`
  * `obb`
  * `trenitalia`
  * `trenitalia_rtvt`
  * `trenord`
  * `ntv_rtiv`
  * `ntv`
  * `hkx`
  * `renfe`
  * `atoc`
  * `benerail`
  * `westbahn`

**Examples**

```jsonc
// Using UIC/provider code
{
  "type": "train",
  "methodology": "ADEME",
  "origin": "db:8011160",        // Berlin Hbf (example code structure)
  "destination": "db:8000105",   // Frankfurt (Main) Hbf (example code structure)
  "number_of_travelers": 2
}

// Using UN/LOCODEs (for multimodal contexts)
{
  "type": "train",
  "methodology": "ADEME",
  "origin": "DEBER",             // Berlin (city code example)
  "destination": "DEFRA",        // Frankfurt (city code example)
  "number_of_travelers": 1
}

// Using coordinates
{
  "type": "train",
  "methodology": "ADEME",
  "origin": "+52.525,13.369",
  "destination": "+50.110,8.682",
  "number_of_travelers": 1
}
```

> **Notes**
>
> * If both `origin`/`destination` **and** `distance_in_km` are provided, `distance_in_km` is used for emissions.
> * Invalid, unsupported, or unresolvable location codes will trigger a **fallback** to generic (non‑journey‑specific) factors consistent with ADEME.

***

## Sample API Response

```json
{
  "carbon_quantity": 6669,
  "carbon_unit": "gram",
  "items": [
    {
      "carbon_quantity": 6669,
      "carbon_unit": "gram",
      "external_reference": "test_2",
      "type": "train",
      "methodology": "ADEME",
      "distance": 435.0,
      "distance_unit": "kilometer"
    }
  ]
}
```

***

## Bibliography

* *GHG information for transport services* (June 2019). Ministère de la Transition Écologique et Solidaire. URL: <https://www.ecologie.gouv.fr/sites/default/files/Information\\_GES%20-%202019.pdf>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-integration.squake.earth/api-calculations-request-response/travel/train/train-ademe.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.