# Train: Base Empreinte 🇫🇷

## High-Level Description

Base Empreinte, managed by ADEME, is a comprehensive environmental impact database combining data from Base Carbone and Base IMPACTS. It supports environmental evaluations by offering multi-criteria data, including greenhouse gas (GHG) emissions and other environmental impacts.

Applied to train travel, Base Empreinte factors in key variables such as train type, location context (e.g., Corsica and Île‑de‑France), grid/fuel, and year of the factor, enabling accurate, audit‑ready emission calculations for stakeholders.

***

## Sample API Requests

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

```json
{
  "expand": ["items"],
  "items": [
    {
      "audit": false,
      "type": "train",
      "methodology": "BASE-EMPREINTE",
      "external_reference": "test_1",
      "number_of_travelers": 1,
      "origin": "FRA",
      "destination": "NCE",
      "train_type": "tram",
      "state": "Ile-de-France",
      "country": "FR",
      "year": "2021"
    }
  ]
}
```

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

```json
{
  "expand": ["items"],
  "audit_for": "<Auditable Entity ID>",
  "items": [
    {
      "audit": true,
      "type": "train",
      "methodology": "BASE-EMPREINTE",
      "external_reference": "test_1",
      "number_of_travelers": 1,
      "origin": "FRA",
      "destination": "NCE",
      "train_type": "tram",
      "state": "Ile-de-France",
      "country": "FR",
      "year": "2021"
    }
  ]
}
```

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

***

## API Request Items

* `"type": "train"` **(required)**
* `"methodology": "BASE-EMPREINTE"` **(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 `ter`, `tgv`, `intercity`, `metro`, `tram`, `trolleybus`, `main_line`. **Default:** `main_line` when only train type is passed.
* `"state"`: Supported regional specificity: `"Corsica"` or `"Ile-de-France"`. **Default:** `"Ile-de-France"`.
* `"country"`: ISO 3166‑1 alpha‑2 country code. **Default:** `"FR"`.
* `"year"`: Year of the factor. **Default:** latest available if not provided.
* `"city_type"`: Used when `state` not provided; one of `population_under_250000` (default) or `population_above_250000`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.

### Default Values

```json
{
  "city_type": "population_under_250000",
  "country": "FR",
  "year": "latest_available",
  "train_type": "main_line",
  "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": "BASE-EMPREINTE",
  "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": "BASE-EMPREINTE",
  "origin": "DEBER",             // Berlin (city code example)
  "destination": "DEFRA",        // Frankfurt (city code example)
  "number_of_travelers": 1
}

// Using coordinates
{
  "type": "train",
  "methodology": "BASE-EMPREINTE",
  "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 Base Empreinte/ADEME practice.

***

## Sample API Response

```json
{
  "carbon_quantity": 4890,
  "carbon_unit": "gram",
  "items": [
    {
      "carbon_quantity": 4890,
      "carbon_unit": "gram",
      "external_reference": "test_1",
      "type": "train",
      "methodology": "BASE-EMPREINTE",
      "distance": 685.0,
      "distance_unit": "kilometer"
    }
  ]
}
```

***

## Bibliography

* ADEME. (2025). Base Empreinte - Données d’impacts environnementaux. <https://www.ademe.fr/base-empreinte>
* ADEME. (2024). Base Carbone Methodological Guide. <https://www.ademe.fr/base-carbone>
* ADEME. (2023). Base IMPACTS & Rail emission factors — official ADEME documentation.