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