# Train: CO2-emissiefactoren 🇳🇱

## High-Level Description

CO2-emissiefactoren is a leading European reference for robust, harmonized CO₂ emission values across sectors, including rail. For train travel, it reflects operational energy, electricity mix, traction efficiency, and (where applicable) infrastructure impacts—supporting consistent, comparable, and decision-useful results.

***

## Sample API Requests

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

```json
{
  "expand": ["items"],
  "items": [
    {
      "audit": false,
      "type": "train",
      "methodology": "CO2-EMISSIEFACTOREN-NL",
      "external_reference": "test",
      "train_type": "international",
      "fuel_type": "average",
      "origin": "AMS",
      "destination": "BER",
      "number_of_travelers": 1,
      "energy_scope": "ttw"
    }
  ]
}
```

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

```json
{
  "expand": ["items"],
  "audit_for": "<Auditable Entity ID>",
  "items": [
    {
      "audit": true,
      "type": "train",
      "methodology": "CO2-EMISSIEFACTOREN-NL",
      "external_reference": "test",
      "train_type": "international",
      "fuel_type": "average",
      "origin": "AMS",
      "destination": "BER",
      "number_of_travelers": 1,
      "energy_scope": "ttw"
    }
  ]
}
```

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

***

## API Request Items

* `"type": "train"` **(required)**
* `"methodology": "CO2-EMISSIEFACTOREN-NL"` **(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 `average`, `international`. **Default:** `average`.
* `"fuel_type"`: One of `diesel`, `electricity`, `average`. **Default:** `average`.
* `"energy_scope"`: Well-to-wheel scope selector. One of `ttw` or `wtw`. **Default:** `wtw`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.

### Default Values

```json
{
  "train_type": "intercity",
  "fuel_type": "average",
  "energy_scope": "wtw",
  "number_of_travelers": 1
}
```

> Note: If your integration assumes `train_type: intercity` as a product-level alias, map it to the dataset’s available categories (`average` or `international`) according to your business rules.

***

## 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": "CO2-EMISSIEFACTOREN-NL",
  "origin": "db:8011160",        // Berlin Hbf (example code structure)
  "destination": "db:8000105",   // Frankfurt (Main) Hbf (example code structure)
  "number_of_travelers": 1,
  "energy_scope": "wtw"
}

// Using UN/LOCODEs (for multimodal contexts)
{
  "type": "train",
  "methodology": "CO2-EMISSIEFACTOREN-NL",
  "origin": "NLAMS",             // Amsterdam (city/port code example)
  "destination": "DEBER",        // Berlin (city code example)
  "number_of_travelers": 1
}

// Using coordinates
{
  "type": "train",
  "methodology": "CO2-EMISSIEFACTOREN-NL",
  "origin": "+52.379,4.900",     // Amsterdam
  "destination": "+52.525,13.369",// Berlin
  "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 the CO2‑emissiefactoren methodology.

***

## Sample API Response

```json
{
  "carbon_quantity": 10132,
  "carbon_unit": "gram",
  "items": [
    {
      "carbon_quantity": 10132,
      "carbon_unit": "gram",
      "external_reference": "test",
      "type": "train",
      "methodology": "CO2-EMISSIEFACTOREN-NL",
      "distance": 596.0,
      "distance_unit": "kilometer"
    }
  ]
}
```

***

## Bibliography

* Lijst emissiefactoren (2025). CO₂-emissiefactoren. <https://www.co2emissiefactoren.nl/>
* Milieu Centraal (n.a.). <https://www.milieucentraal.nl/>