# Train: EPA 🇺🇸

💡 **High-Level Description**

The **US EPA GHG Emission Factors Hub** provides passenger-rail emission factors used for corporate greenhouse gas (GHG) accounting in the United States. For trains, factors are expressed as **gCO₂e per passenger-kilometer** and include **CO₂, CH₄, and N₂O** aggregated using the EPA’s 100-year GWPs for the given Hub year. In this implementation:

* Units: **gCO₂e/pax-km**
* Scope: **well-to-wheel (WTW)** representation of emissions reflected in EPA’s factors
* Coverage: **intercity** (national average & route-specific), **commuter rail**, and **transit rail**

> **Note on versions:** If `methodology_version` is omitted, SQUAKE will **always use the latest supported EPA Hub year**. Pinning is recommended for reproducibility.

***

### **Sample API Requests**

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

```json
{
  "expand": ["items"],
  "items": [
    {
      "audit": false,
      "type": "train",
      "external_reference": "test_1",
      "distance_in_km": 500,
      "number_of_travelers": 1,
      "methodology": "US-EPA",
      "train_type": "intercity_national_average"
    }
  ]
}
```

#### 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",
      "distance_in_km": 500,
      "number_of_travelers": 1,
      "methodology": "US-EPA",
      "train_type": "intercity_national_average"
    }
  ]
}
```

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

***

### **API Request Items**

* `"type": "train"` **(required)**
* `"methodology": "US-EPA"` **(required)**
* `"methodology_version"`: EPA Hub year (e.g., `"2023"`). **Optional**. If omitted, the calculation **defaults to the latest supported year**.
* `"external_reference"`: Your unique identifier for correlating responses. Max length 128 chars.
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"distance_in_km"`: **Preferred** distance input. If both `distance_in_km` and `origin`/`destination` are given, `distance_in_km` is used.
* `"origin"` and `"destination"` (optional): If provided, SQUAKE will resolve the rail distance. Accepts IATA/ICAO/UNLOCODE/postal formats or `"lat,lon"` (e.g., `"+40.712,-74.006"`).\
  \&#xNAN;*Note: For EPA factors, the **train type** should match U.S. service classes (see below).*
* `"train_type"`: **Supported**
  * `"intercity_northeast_corridor"`
  * `"intercity_other_routes"`
  * `"intercity_national_average"`
  * `"commuter_rail"`
  * `"transit_rail"`
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.

**Defaults**

* `"train_type": "intercity_national_average"`
* `"number_of_travelers": 1"`
* If `"methodology_version"` is omitted → **latest supported EPA Hub year**.

***

## 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., `atoc:1072` or `amtrak:NYP` as illustrative code styles)
* **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 a provider code (illustrative; US context)
{
  "type": "train",
  "methodology": "US-EPA",
  "origin": "atoc:1072",          // Example code structure
  "destination": "atoc:5935",
  "number_of_travelers": 1,
  "train_type": "intercity_national_average"
}

// Using UN/LOCODEs (for multimodal contexts)
{
  "type": "train",
  "methodology": "US-EPA",
  "origin": "USNYC",              // New York City
  "destination": "USWAS",         // Washington, DC
  "number_of_travelers": 1,
  "train_type": "intercity_northeast_corridor"
}

// Using coordinates
{
  "type": "train",
  "methodology": "US-EPA",
  "origin": "+40.750,-73.993",    // Near NYC Penn Station
  "destination": "+38.897,-77.007",// Washington, DC
  "number_of_travelers": 1,
  "train_type": "intercity_northeast_corridor"
}
```

> **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 US-EPA methodology.

***

### **Computation**

Let **EF** be the factor in gCO₂e/pax-km for the chosen `train_type` and `methodology_version` (or latest if omitted).

```
total_gCO2e = EF × distance_in_km × number_of_travelers
```

All outputs are returned in **grams** by default.

***

### **Sample API Response**

```json
{
  "carbon_quantity": 18127.337,
  "carbon_unit": "gram",
  "items": [
    {
      "carbon_quantity": 18127.337,
      "carbon_unit": "gram",
      "external_reference": "test_case_1",
      "type": "train",
      "methodology": "US-EPA",
      "distance": 500.0,
      "distance_unit": "kilometer",
      "train_type": "intercity_northeast_corridor"
    }
  ]
}
```

***

### **Bibliography**

* **US EPA.** *GHG Emission Factors Hub* (Passenger Rail). <https://www.epa.gov/climateleadership/ghg-emission-factors-hub>