# Train: Green Travel Pledge

💡 **High‑Level Description**

**Green Travel Pledge (GTP)** is an industry initiative led by the UK **Rail Delivery Group (RDG)** providing recognised, route‑level carbon data for rail journeys in Great Britain. Under the umbrella **Green Travel Data (GTD)** programme, RDG publishes per‑journey and per‑passenger emissions so businesses can compare rail with car and air and drive modal shift.

GTP focuses on **per‑passenger CO₂e** for specific **origin–destination** pairs and, where available, **seat class**. When a journey‑specific figure is not provided, the dataset offers fallback factors per passenger‑kilometre. SQUAKE implements both layers with deterministic fallbacks and preserves comparison values for **diesel car, plug‑in hybrid, battery electric car, and air** for auditability.

***

### **Sample API Requests**

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

```json
{
  "expand": ["items"],
  "items": [
    {
      "audit": false,
      "type": "train",
      "external_reference": "test_1",
      "origin": "GRF",
      "destination": "MBR",
      "number_of_travelers": 1,
      "seat_type": "second_class",
      "methodology": "GREEN-TRAVEL-PLEDGE",
      "departure_date": "2025-05-03"
    }
  ]
}
```

#### 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_1",
      "origin": "GRF",
      "destination": "MBR",
      "number_of_travelers": 1,
      "seat_type": "second_class",
      "methodology": "GREEN-TRAVEL-PLEDGE",
      "departure_date": "2025-05-03"
    }
  ]
}
```

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

***

### **API Request Items**

* `"type"`: `"train"` **(required)**
* `"methodology"`: `"GREEN-TRAVEL-PLEDGE"` **(required)**
* `"external_reference"`: Correlates request/response (max 128 chars).
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"origin"` / `"destination"`: Stations per GTD (GB rail). Standard resolvers (CRS/3‑letter, TIPLOC, name) supported.
* `"departure_date"`: ISO date `YYYY-MM-DD`. Used to select the **latest dataset published on or before** this date. If omitted, SQUAKE uses the **latest available dataset** at calculation time (captured in metadata as `dataset_date`).
* `"distance_in_km"` (optional): If provided, used **only for fallback** when per‑journey emissions are not available and per‑pax‑km factors must be applied.
* `"seat_type"` (optional): One of `"first_class"`, `"second_class"`, `"average"` (**default:** `"average"`). See mapping below.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.

***

### **Seat Type Mapping**

* Client → GTP:
  * `"second_class"` → `"standard"`
  * `"first_class"` → `"first"`
  * `"average"` → use dataset `"average"` (where available) or computed average if class values are missing.

**Zero‑value guardrails**

* If the class value (**standard/first**) is present but equals `0`, SQUAKE uses the **`average`** value for that journey.
* If class **and** average are missing or zero, SQUAKE enters **fallback mode** (see below).

***

### **Calculation & Fallbacks**

1. **Primary (per‑journey CSV)** – `gtd-emissions-output-by-journey.csv`
   * Use the **exact O–D** row for the specified `departure_date` dataset.
   * Choose class‑specific value (`first` or `standard`) or `average` per the mapping/guards above.
   * Multiply by `number_of_travelers`. Result is **grams CO₂e** if dataset is already per journey; otherwise convert as per dataset units.
2. **Fallback (per‑passenger‑km CSV)** – `gtd-emissions-output-by-passenger.csv`
   * Take factor **kgCO₂e/pax/km**; compute:

     ```
     grams = factor_kg_per_pax_km × distance_in_km × number_of_travelers × 1000
     ```
   * `distance_in_km` is required for fallback. If not provided, SQUAKE attempts to resolve rail distance; on failure, returns `distance_required` error.

**Comparison Modes (saved for audit)**

* Alongside train emissions, SQUAKE stores comparison values (if provided by GTP dataset) for:
  * **Diesel Car**, **Plug‑in Hybrid Electric Car**, **Battery Electric Car**, **Air**.
* If a comparison value equals `0`, SQUAKE records `"N/A"` meaning **Not Comparable**.

***

### **Default Values**

* `"seat_type": "average"`
* Dataset selection: **latest published on/ before `departure_date`**; otherwise **latest available** (metadata includes `dataset_date`).

***

### **Sample API Response**

```json
{
  "carbon_quantity": 1580,
  "carbon_unit": "gram",
  "items": [
    {
      "carbon_quantity": 1580,
      "carbon_unit": "gram",
      "external_reference": "test_1",
      "type": "train",
      "methodology": "GREEN-TRAVEL-PLEDGE",
      "origin": "GRF",
      "destination": "MBR",
      "seat_type": "second_class",
      "dataset_date": "2025-05-01",
      "data_source": "journey",
      "distance": 0.0,
      "distance_unit": "kilometer",
      "metadata": {
        "comparison": {
          "diesel_car_g": 4860,
          "phev_car_g": 3140,
          "bev_car_g": 1430,
          "air_g": "N/A"
        }
      }
    }
  ]
}
```

***

### **Versions / Dataset Updates**

* GTP datasets are periodically refreshed. SQUAKE selects the **latest dataset at or before `departure_date`** (or latest available if `departure_date` is omitted) and returns `dataset_date` for traceability.

***

### **Bibliography**

* Rail Delivery Group — **Green Travel Data / Green Travel Pledge** (programme overview & calculator).\
  <https://www.raildeliverygroup.com/uk-rail-industry/green-travel-data.html>