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" to expand. 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

MethodologyActivityWhat algorithm_specifics holds
TIMFlightTIM dataset, contrail rating, and the result in both energy scopes
GATE4FlightResolution level and the GATE4 record behind the figure
REMTrainTier, factor and its source, energy scope alignment, train-type fallback, distance and seat factor
Green Travel DataTrainTimetable release, type of figure, and seat type used
NOS-GESTES-CLIMATHotelPer-night factor and number of nights
GLEC and Clean CargoFreight and logistics sitesResult in the requested scope and well-to-wheel, factor, tonne-kilometres, reporting year, and transport mode
DIN EN 16258FreightEnergy 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

POST /v2/calculations
{
  "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

200 OKapplication/json
{
  "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

FieldTypeDescription
dataset_typestringTIM 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_bucketstringTIM'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_wtwintegerTIM result in grams, well-to-wake: fuel production and supply plus combustion.
co2_in_grams_ttwintegerTIM result in grams, tank-to-wake: combustion only.

Reading the example

  • LH996 from FRA to AMS is 367 km, for one economy passenger departing on 2027-06-01.
  • dataset_type is google_tim, so no fallback applied.
  • carbon_quantity is 56,688 g, the same as co2_in_grams_wtw, because well-to-wake is the default energy scope. Options that change the TIM figure, such as logistics_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_wtw and co2_in_grams_ttw together: 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"
}
FieldTypeDescription
match_levelstringResolution level that answered the flight, from exact down to averages over the route. The GATE4 page lists the levels in order.
matched_airlinestringAirline of the record behind the figure.
matched_flight_numberintegerFlight number of that record, or null for averaged levels.
matched_departure_datestringDeparture date of that record.
matched_flightsintegerNumber of records averaged; 1 for an exact or nearest-date match.
booking_class_usedstringCabin 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

POST /v2/calculations
{
  "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

200 OKapplication/json
{
  "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

FieldTypeDescription
tierintegerStep 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.
methodologystringType of source behind the factor. operator_reported is a factor the operator publishes itself (tier 1).
calculation_basisstringHow REM uses the source. source_reported means REM takes the factor as the source publishes it.
operator_matchedstringOperator whose factor REM applied.
country_matchedstringCountry of the factor, as a lower-case ISO 3166-1 alpha-2 code.
year_matchedintegerReporting year of the factor.
source_linksarray of stringsPublications the factor comes from.

Factor and energy scope

FieldTypeDescription
gco2e_per_pax_kmdecimal stringFactor applied, in grams CO₂e per passenger-kilometre, in the energy scope of the result.
energy_scopestringEnergy scope of the result: wtw (well-to-wheel, the default) or ttw (tank-to-wheel).
source_energy_scopestringWhat 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_wtwdecimal stringFactor in the well-to-wheel scope after REM aligned the source's scope.
retained_gco2e_per_pax_km_ttwdecimal stringFactor 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

FieldTypeDescription
requested_train_typestringtrain_type from your request.
train_type_fallback_candidatesarray of stringsTrain types REM tried, in order.
train_type_matchedstringTrain type of the factor REM found.
resolved_train_typestringTrain type of the calculation.
train_type_fallback_reasonstringWhy 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

FieldTypeDescription
calculation_strategystringHow REM applies the factor. single_factor means one factor for the whole distance.
distance_sourcestringWhere 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_factordecimal stringMultiplier for the seat_type.

Reading the example

  • SJ from Stockholm to Malmo is 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, or intercity, so it takes the average factor 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"
}
FieldTypeDescription
timetable_start, timetable_endstringFirst and last day of the timetable release SQUAKE used.
timetable_covers_departure_datebooleantrue when that timetable covers the departure_date. Otherwise SQUAKE uses the latest release.
figurestringjourney when the figure is the journey's own. Otherwise SQUAKE uses the per-passenger-kilometre figure.
seat_type_usedstringSeat 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
}
FieldTypeDescription
factor_kg_co2e_per_nightnumberFootprint per night in kg CO₂e.
factor_g_co2e_per_nightnumberThe same factor in grams.
number_of_nightsnumberNights 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"
  }
}
FieldTypeDescription
algorithm_typestringglec or clean_cargo.
data.co2e_in_gnumberResult in grams CO₂e, in the energy scope you requested. It matches carbon_quantity in grams.
data.co2e_emissions_wtw_in_gnumberWell-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_gnumberEmission factor in grams CO₂e per tonne-kilometre.
data.tonne_kmnumberTransport work: cargo tonnes times distance.
data.co2e_per_tonne_in_gnumberFor 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_yearintegerYear of the factor set.
data.transportation_modestringMode 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
  }
}
FieldTypeDescription
data.energy_factor_ttw_in_MJnumberEnergy figure in megajoules, tank-to-wheel.
data.energy_factor_wtw_in_MJnumberEnergy figure in megajoules, well-to-wheel.
data.ghg_emissions_ttw_in_gnumberTank-to-wheel emissions in grams.
data.ghg_emissions_wtw_in_gnumberWell-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

On this page