Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Train: REM

Documentation on this page is aligned to REM methodology v2.6 (integration and Calculation API payloads). Use "methodology": "REM" in all new integrations.

Set methodology to REM to use REM. If you omit methodology on a train item, the API uses your client's configured train default.

Overview

REM is an operator- and country-aware rail methodology. It selects an emission factor (grams CO₂e per passenger-kilometre) using a deterministic tiered resolver, then multiplies by distance and passenger count.

Supplying operator_name, ISO country codes, departure_date, and energy_scope when you have them improves tier matching and makes results easier to audit.

Factor resolution (tiers)

REM applies this order:

  1. Tier 1 — Operator-reported Used when operator_name matches operator-specific factors for the requested energy_scope, train_type, and (when needed) fuel_type / year.

  2. Tier 2 — Operator-reported mix Used when operator_name matches operator-specific energy mix for the requested energy_scope, train_type, and (when needed) fuel_type / year.

  3. Tier 3 — Country-published Uses country-level methodology data when Tier 1 and Tier 2 do not apply and a country context is available (see Country context below).

  4. Tier 4 — Activity-based Uses fuel, traction mix, and electricity carbon intensity data for the country/region when Tier 3 does not yield a factor.

  5. Tier 5 — Global constant Well-to-wheel global rail averages (IEA-based constants), with a pre/post cut-off driven by departure_date when present.

Country context for Tiers 3–4: The resolver uses origin_country if set, otherwise destination_country (both optional). Values should be ISO 3166-1 alpha-2 (e.g. DE, SE). The API accepts other resolvable country inputs and normalizes to alpha-2 where possible (e.g. UK → GB). If neither country field is available, Tier 1 and Tier 2 may still apply; otherwise resolution falls through toward Tier 5.

Distance handling

You must provide one of the following (after validation):

  • origin and destination (resolved to a route distance), or

  • distance_in_km (positive number), or

  • route_coords: an array of at least two [longitude, latitude] pairs (WGS84). Longitude must be in [-180, 180], latitude in [-90, 90].

Precedence: If distance_in_km is set together with origin / destination, distance_in_km is used for the calculation distance.

Corrections:

  • If you send route_coords, the API computes a border-aware path distance (per-country segments, train-type detour factor from REM data). That total becomes the distance used for emissions; no additional "air distance" correction is applied on top.

  • If you send distance_in_km without route_coords, REM still applies the air-distance correction used for straight-line or user-supplied distances (so driven distance is consistent with the methodology).

  • For audit / debugging, expanded item metadata may include a border_distance_breakdown when route_coords were used (sequential segments and totals per ISO alpha-3 country). If some segments cannot be attributed to a country, a warning may be present.

Sample API Requests

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

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

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

C. Route path (route_coords) without origin/destination

When route_coords is valid, origin and destination are not required for distance validation.

API request fields

  • type: "train" (required).

  • methodology: "REM". If omitted, the API uses your client's configured train default.

  • external_reference: Unique id for the item in the request (helps map results to inputs). Max length 128 characters.

  • number_of_travelers: Integer ≥ 1. Default 1.

  • origin, destination: Location strings as in other train methodologies (addresses, IATA/ICAO, UN/LOCODE, coordinates, UIC/provider codes — see Origin/destination formats below). Required unless you supply distance_in_km or valid route_coords.

  • distance_in_km: Optional. If provided together with origin / destination, this value wins. Subject to REM air-distance correction unless route_coords are used.

  • route_coords: Optional. Array of [lon, lat] pairs; minimum 2 points. Each pair must have exactly two numbers. Used for border-aware distance and detour factor.

  • train_type: One of: average, high_speed, intercity, regional, long_distance, commuter, tram, metro, light_rail, urban_rail. API default when omitted: average.

  • fuel_type: diesel, electricity, hvo, hydrogen. Default diesel. Used for Tier 1 and Tier 2 disambiguation when an operator has multiple fuel rows, and for Tier 3 and Tier 4 modelling where applicable.

  • seat_type: average, first_class, or second_class. Default average.

  • operator_name: Optional; enables Tier 1 or Tier 2 when the operator exists in the REM operator database. Contact product@squake.earth for the full currently supported list of operators.

  • departure_date: Optional. ISO 8601 calendar date only: YYYY-MM-DD (date-only, not a full timestamp). Used to select year-matched factors. If invalid, the API returns: Departure date '<value>' is not a valid ISO-8601 date.

  • origin_country, destination_country: Optional. ISO 3166-1 alpha-2 recommended (e.g. DE, FR). Other resolvable country strings may be accepted and normalized to alpha-2. Invalid codes return a parameter error. For country-based tiers, origin_country is preferred over destination_country when both are set.

  • energy_scope: wtw (well-to-wheel, default) or ttw (tank-to-wheel). Invalid values return an error listing allowed scopes.

  • audit: Optional boolean for immutable audit records (feature must be enabled for your account).

Origin/destination formats (enriched)

We will try to resolve origin / destination regardless of format. Ideally:

  • Addresses: Post/standard postal format.

  • Airports: IATA/ICAO (^[A-Z]{3,4}$, e.g. MUC).

  • Ports / trade: UN/LOCODE (^[A-Z]{2}\W?[A-Z2-9]{3}$, e.g. DEHAM).

  • Coordinates: ^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$ (e.g. "+40.712,-74.006").

UIC and provider codes

  • Invalid or unsupported codes may trigger fallback to more generic factors (non-journey-specific).

  • 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

Notes

  • If both origin/destination and distance_in_km are provided, distance_in_km is used.

  • Unresolvable locations produce validation errors or methodology fallbacks as described for train generally.

Sample API response

When you expand items, each train item may include algorithm_specifics describing the resolved REM tier and matched metadata (for example tier, energy_scope, gco2e_per_pax_km, year_matched, country_matched, operator_matched, source_links, and resolver details). Exact shape follows the live API.

The numeric / string formatting of algorithm_specifics fields matches the production API; treat gco2e_per_pax_km as a decimal string or number per response schema.

White Paper

PreviousTrain: Green Travel Pledge
NextLogistics

Last updated