Algorithm specifics
How to read the methodology details returned with each calculation item, from TIM and REM to GATE4, Green Travel Data and the freight methodologies.
Each calculation item can include an algorithm_specifics object. It shows how the methodology reached the item's carbon_quantity: which dataset, tier or record matched, which emission factor applied, and where one of your inputs fell back to a more general value.
- How to get it: add
"items"toexpand. Without it, the response contains only the totals. - What it contains: the keys depend on the
methodology. The table below lists the methodologies that return the object, and the sections after it explain every field. - What to use it for: store it with the booking as part of your audit trail, show quality signals such as the REM tier or the TIM contrail rating, and detect fallbacks.
- What to avoid: report
carbon_quantity, not a figure rebuilt from these keys. Read the keys you need and ignore the others, so new keys don't break your integration. - Number formats: REM returns factors and multipliers as decimal strings such as
"0.27". Parse them with a decimal type to keep their precision. Other methodologies return numbers.
The object is part of the Perform a Calculation response in the API reference.
Which methodologies return it
| Methodology | Activity | What algorithm_specifics holds |
|---|---|---|
| TIM | Flight | TIM dataset, contrail rating, and the result in both energy scopes |
| GATE4 | Flight | Resolution level and the GATE4 record behind the figure |
| REM | Train | Tier, factor and its source, energy scope alignment, train-type fallback, distance and seat factor |
| Green Travel Data | Train | Timetable release, type of figure, and seat type used |
| NOS-GESTES-CLIMAT | Hotel | Per-night factor and number of nights |
| GLEC and Clean Cargo | Freight and logistics sites | Result in the requested scope and well-to-wheel, factor, tonne-kilometres, reporting year, and transport mode |
| DIN EN 16258 | Freight | Energy and emissions in both scopes, or fuel factors for rail freight |
Methodologies that aren't in this table don't document an algorithm_specifics object.
Flight: TIM
For flights calculated with TIM, algorithm_specifics shows which TIM dataset produced the result, TIM's contrail rating, and the result in both energy scopes.
Sample request
{
"expand": ["items"],
"items": [
{
"type": "flight",
"methodology": "TIM",
"origin": "FRA",
"destination": "AMS",
"number_of_travelers": 1,
"booking_class": "economy",
"flight_number": "LH996",
"external_reference": "test",
"departure_date": "2027-06-01"
}
]
}Sample response
{
"carbon_quantity": 56688,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 56688,
"carbon_unit": "gram",
"external_reference": "test",
"type": "flight",
"methodology": "TIM",
"distance": 367.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"dataset_type": "google_tim",
"contrails_impact_bucket": "NEGLIGIBLE",
"co2_in_grams_wtw": 56688,
"co2_in_grams_ttw": 47134
}
}
]
}Fields
| Field | Type | Description |
|---|---|---|
dataset_type | string | TIM dataset that produced the result. google_tim is the standard dataset. google_tim_fallback means the request didn't hold enough data for a precise match. historical_google_tim is TIM's historical dataset; the TIM page describes its tiers. |
contrails_impact_bucket | string | TIM's rating of the flight's contrail warming: NEGLIGIBLE, MODERATE, SEVERE, or UNSPECIFIED when no rating exists. It's for display only and isn't part of carbon_quantity. |
co2_in_grams_wtw | integer | TIM result in grams, well-to-wake: fuel production and supply plus combustion. |
co2_in_grams_ttw | integer | TIM result in grams, tank-to-wake: combustion only. |
Reading the example
LH996fromFRAtoAMSis 367 km, for one economy passenger departing on 2027-06-01.dataset_typeisgoogle_tim, so no fallback applied.carbon_quantityis 56,688 g, the same asco2_in_grams_wtw, because well-to-wake is the default energy scope. Options that change the TIM figure, such aslogistics_hub, can make the two differ.- Combustion accounts for 47,134 g (
co2_in_grams_ttw). The difference of 9,554 g, about 17% of the total, is the well-to-tank part: producing and delivering the fuel. - The contrail rating is
NEGLIGIBLE. It doesn't change the CO₂e figure. - Don't add
co2_in_grams_wtwandco2_in_grams_ttwtogether: they describe the same flight in two scopes.
Flight: GATE4
For flights calculated with GATE4, algorithm_specifics shows which GATE4 record answered the flight.
"algorithm_specifics": {
"match_level": "exact",
"matched_airline": "2J",
"matched_flight_number": 520,
"matched_departure_date": "2024-10-01",
"matched_flights": 1,
"booking_class_used": "business"
}| Field | Type | Description |
|---|---|---|
match_level | string | Resolution level that answered the flight, from exact down to averages over the route. The GATE4 page lists the levels in order. |
matched_airline | string | Airline of the record behind the figure. |
matched_flight_number | integer | Flight number of that record, or null for averaged levels. |
matched_departure_date | string | Departure date of that record. |
matched_flights | integer | Number of records averaged; 1 for an exact or nearest-date match. |
booking_class_used | string | Cabin the figure belongs to. When the aircraft doesn't offer the requested cabin, GATE4 falls back to the next lower one and reports it here. |
For a routing item, these fields appear on each entry of legs (with "legs" in expand) instead of on the item.
Train: REM
For trains calculated with REM, the Rail Emissions Model, algorithm_specifics shows where the emission factor comes from, how REM aligned its energy scope, which train type it matched, and how it turned the factor into the result.
Sample request
{
"expand": ["items"],
"items": [
{
"type": "train",
"external_reference": "test_1",
"origin": "Stockholm",
"destination": "Malmo",
"number_of_travelers": 1,
"train_type": "high_speed",
"seat_type": "second_class",
"fuel_type": "electricity",
"operator_name": "sj",
"methodology": "REM"
}
]
}Sample response
{
"carbon_quantity": 135,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 135,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "train",
"methodology": "REM",
"distance": 554.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"tier": 1,
"energy_scope": "wtw",
"gco2e_per_pax_km": "0.27",
"year_matched": 2025,
"country_matched": "se",
"operator_matched": "sj",
"source_links": [
"https://cdn.sj.se/files/hulddl9x/production/80bf35f01f083aa970bee79612688dc340b78473.pdf/SJ-A%CC%8AHR-2025-t.pdf",
"https://www.sj.se/en/about-sj/sustainability"
],
"methodology": "operator_reported",
"calculation_basis": "source_reported",
"source_energy_scope": "iso_14083_train_energy_plus_refrigerants",
"retained_gco2e_per_pax_km_ttw": "0.0",
"retained_gco2e_per_pax_km_wtw": "0.27",
"requested_train_type": "high_speed",
"resolved_train_type": "average",
"train_type_matched": "average",
"train_type_fallback_candidates": [
"high_speed",
"long_distance",
"intercity",
"average"
],
"train_type_fallback_reason": "average_train_type_fallback",
"calculation_strategy": "single_factor",
"distance_source": "origin_destination",
"seat_factor": "0.9"
}
}
]
}Where the factor comes from
| Field | Type | Description |
|---|---|---|
tier | integer | Step of the REM factor ladder that produced the factor: 1 operator-reported factor, 2 operator energy mix, 3 country-published data, 4 activity-based model, 5 global average. A lower tier means REM found a more specific source for this trip. |
methodology | string | Type of source behind the factor. operator_reported is a factor the operator publishes itself (tier 1). |
calculation_basis | string | How REM uses the source. source_reported means REM takes the factor as the source publishes it. |
operator_matched | string | Operator whose factor REM applied. |
country_matched | string | Country of the factor, as a lower-case ISO 3166-1 alpha-2 code. |
year_matched | integer | Reporting year of the factor. |
source_links | array of strings | Publications the factor comes from. |
Factor and energy scope
| Field | Type | Description |
|---|---|---|
gco2e_per_pax_km | decimal string | Factor applied, in grams CO₂e per passenger-kilometre, in the energy scope of the result. |
energy_scope | string | Energy scope of the result: wtw (well-to-wheel, the default) or ttw (tank-to-wheel). |
source_energy_scope | string | What the source's figure covers. iso_14083_train_energy_plus_refrigerants is train energy as defined in ISO 14083, plus refrigerant leakage. |
retained_gco2e_per_pax_km_wtw | decimal string | Factor in the well-to-wheel scope after REM aligned the source's scope. |
retained_gco2e_per_pax_km_ttw | decimal string | Factor in the tank-to-wheel scope after the same alignment. Electric trains have no emissions at the train itself, so this is zero for them. |
Train type
| Field | Type | Description |
|---|---|---|
requested_train_type | string | train_type from your request. |
train_type_fallback_candidates | array of strings | Train types REM tried, in order. |
train_type_matched | string | Train type of the factor REM found. |
resolved_train_type | string | Train type of the calculation. |
train_type_fallback_reason | string | Why the train type differs from your request. average_train_type_fallback means no factor exists for the requested type, so REM takes the operator's average. |
Distance and seat
| Field | Type | Description |
|---|---|---|
calculation_strategy | string | How REM applies the factor. single_factor means one factor for the whole distance. |
distance_source | string | Where the distance comes from. origin_destination means REM resolved it from origin and destination. For distance_in_km and route_coords, see Distance handling. |
seat_factor | decimal string | Multiplier for the seat_type. |
Reading the example
- SJ from
StockholmtoMalmois 554 km, resolved from origin and destination, for one traveller in second class on an electric high-speed train. - Tier 1: SJ publishes its own factor, 0.27 g CO₂e per passenger-kilometre for 2025, and REM uses it as published (
source_reported). The links point to the annual and sustainability report that SJ publishes. - REM has no SJ factor for
high_speed,long_distance, orintercity, so it takes theaveragefactor that SJ reports (average_train_type_fallback). - The train is electric, so REM retains 0.0 g in the tank-to-wheel scope and 0.27 g in the well-to-wheel scope.
- Second class has a seat factor of 0.9. The result is 0.27 g × 554 km × 1 traveller × 0.9 = 134.6 g, returned as 135 g.
Train: Green Travel Data
For trains calculated with Green Travel Data, algorithm_specifics names the timetable release behind the figure.
"algorithm_specifics": {
"timetable_start": "2025-12-14",
"timetable_end": "2026-05-16",
"timetable_covers_departure_date": true,
"figure": "journey",
"seat_type_used": "second_class"
}| Field | Type | Description |
|---|---|---|
timetable_start, timetable_end | string | First and last day of the timetable release SQUAKE used. |
timetable_covers_departure_date | boolean | true when that timetable covers the departure_date. Otherwise SQUAKE uses the latest release. |
figure | string | journey when the figure is the journey's own. Otherwise SQUAKE uses the per-passenger-kilometre figure. |
seat_type_used | string | Seat type whose figure the calculation uses. |
Hotel: NOS-GESTES-CLIMAT
For hotel stays calculated with NOS-GESTES-CLIMAT, algorithm_specifics holds the per-night factor.
"algorithm_specifics": {
"factor_kg_co2e_per_night": 6.94,
"factor_g_co2e_per_night": 6940,
"number_of_nights": 2
}| Field | Type | Description |
|---|---|---|
factor_kg_co2e_per_night | number | Footprint per night in kg CO₂e. |
factor_g_co2e_per_night | number | The same factor in grams. |
number_of_nights | number | Nights from your request. The result is the factor times the nights: 6,940 g × 2 = 13,880 g. |
Freight: GLEC and Clean Cargo
For freight and logistics sites calculated with GLEC or Clean Cargo, algorithm_specifics names the algorithm and puts the figures in data.
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 713817,
"co2e_emissions_wtw_in_g": 835318,
"co2e_per_tonne_km_in_g": 9,
"tonne_km": 75938,
"reporting_year": 2024,
"transportation_mode": "sea_transportation"
}
}| Field | Type | Description |
|---|---|---|
algorithm_type | string | glec or clean_cargo. |
data.co2e_in_g | number | Result in grams CO₂e, in the energy scope you requested. It matches carbon_quantity in grams. |
data.co2e_emissions_wtw_in_g | number | Well-to-wheel result in grams. It equals co2e_in_g when you request wtw, and is higher when you request ttw, as in the sea freight example. |
data.co2e_per_tonne_km_in_g | number | Emission factor in grams CO₂e per tonne-kilometre. |
data.tonne_km | number | Transport work: cargo tonnes times distance. |
data.co2e_per_tonne_in_g | number | For logistics sites, which have no distance: emission factor in grams CO₂e per tonne handled. It replaces the per tonne-kilometre factor and tonne_km. |
data.reporting_year | integer | Year of the factor set. |
data.transportation_mode | string | Mode the factor belongs to, such as road_transportation, rail_transportation, sea_transportation, air_transportation, inland_waterways_transportation, or logistics_site. |
Freight: DIN EN 16258
For freight calculated with DIN EN 16258, algorithm_type is DIN-EN-16258 and data reports energy and emissions in both scopes.
"algorithm_specifics": {
"algorithm_type": "DIN-EN-16258",
"data": {
"energy_factor_ttw_in_MJ": 926,
"energy_factor_wtw_in_MJ": 1103,
"ghg_emissions_ttw_in_g": 68994,
"ghg_emissions_wtw_in_g": 83825
}
}| Field | Type | Description |
|---|---|---|
data.energy_factor_ttw_in_MJ | number | Energy figure in megajoules, tank-to-wheel. |
data.energy_factor_wtw_in_MJ | number | Energy figure in megajoules, well-to-wheel. |
data.ghg_emissions_ttw_in_g | number | Tank-to-wheel emissions in grams. |
data.ghg_emissions_wtw_in_g | number | Well-to-wheel emissions in grams. carbon_quantity matches the figure for the energy scope you requested: the road freight example asks for ttw and returns 68,994 g. |
Rail freight reports fuel factors instead: fuel_consumption_per_tonne_km, fuel_to_co2, train_type, reporting_year, and transportation_mode.
Sources
- Google. Travel Impact Model. github.com/google/travel-impact-model
- SQUAKE. Rail Emissions Model (REM) white paper. squake.earth/resources/rail-emission-model-whitepaper
- ISO 14083:2023. Greenhouse gases: Quantification and reporting of greenhouse gas emissions arising from transport chain operations.