Table of Contents

Harmonized request / response overview

Normalization notes

Mirrored from /mnt/DATA/Nextcloud/ADD ideas UG/Products/co2api/apis/request_response_new.md. Origin: product:co2api. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.

Harmonized request / response overview

This table consolidates the previously separate provider tables into one consistent structure.

Provider	Operation / variant	Endpoint	Request shape	Response shape	Mapping / use notes	Status
calco2la.to	Flight estimate	`POST /api/flight` or planned `POST /api/v1/flight/estimate`	`{ api_key?, departureDate?, rfi?, pricePerTon?, flights:[{ departure, arrival, passengerCount, flightCount, travelClass, charter, aircraftType, departureDate, calculationMethod, via, rfi, pricePerTon }] }`	`{ status, errors, departureDate, rfi, pricePerTon, co2, co2WithoutRfi, offsetInEUR, distance, distanceInCriticalAltitudes, fuelInLiter, flights:[...] }`	Native/reference provider. Maps well to `EmissionCalculationResult` with nested `segments`.	High
Atmosfair	Flight estimate	`POST /api/emission/flight`	`{ accountId/username, password, calculationMethod?, flights:[{ departure/arrival OR flightNumber/departureDate, passengerCount, flightCount, travelClass, charter, aircraftType }] }`	`{ status, errors, offsetInEUR, co2, co2WithoutRfi, cruiseAltitude, distance, distanceInCriticalAltitudes, fuelInLiter, flights:[...] }`	Very similar to calco2la.to; supports multi-hop by sending one flight element per segment. Fits `EmissionCalculationResult.segments`.	High
Atmosfair	Rail / hotel / car rental estimate	`POST /api/emission/rail`, `POST /api/emission/hotel`, `POST /api/emission/carrental`	Rail supports stations or distance; hotel supports overnights or price models; car rental supports distance, price, or days.	Shared simple pattern: `{ status, errors, offsetInEUR, co2 }`; car follows hotel pattern.	Not flight-only. Confirms the unified schema should remain domain-neutral for future `travel.rail`, `travel.hotel`, `travel.car`.	High
Google TIM	Direct flight emissions	`POST /v1/flights:computeFlightEmissions`	`{ flights:[{ origin, destination, operatingCarrierCode, flightNumber, departureDate:{ year, month, day } }] }`	`{ flightEmissions:[{ flight, source, emissionsGramsPerPax:{ first, business, premiumEconomy, economy }, ... }], modelVersion }`	Requires flight-number-level data. Produces per-cabin-class grams per passenger, not one selected cabin result.	High
Google TIM	Scope 3 flight emissions	`POST /v1/flights:computeScope3FlightEmissions`	`{ flights:[{ departureDate, cabinClass, origin?, destination?, carrierCode?, flightNumber?, distanceKm? }], modelVersion? }`	`{ flightEmissions:[{ flight, wtwEmissionsGramsPerPax, ttwEmissionsGramsPerPax, wttEmissionsGramsPerPax, source }], modelVersion }`	Best Google TIM option for Scope 3 reporting. Maps to `wtwKg`, `ttwKg`, `wttKg`.	High
myclimate	Flight Calculator v1	`POST /v1/flight_calculators.json`	`{ from, to, via?, passengers?, roundtrip?, flight_class? }`	`{ kg, km, fuel_kg_per_passenger, price_in_eur_cents?, price_in_chf_rappen?, input_params, errors? }`	Simple root-result mapping. Limited leg detail.	High
myclimate	Flight Calculator v2	`POST /v2/flight_calculators.json`	Same as v1 plus `aircraft_type_leg_1`, `aircraft_type_leg_2`.	Same general response as v1.	Better than v1 if aircraft type is available. Still mainly root-result mapping.	High
myclimate	Bulk Flight Calculator	`POST /v1/bulk_flight_calculators.json`	`{ flights:[{ id, from, to, aircraft_type?, flight_class }] }`	`{ sum_co2eq_kg, sum_km, sum_price_in_eur_cents?, flights:[{ id, from, to, flight_class, aircraft_type, co2eq_kg, km, fuel_kg_per_passenger, price_in_eur_cents?, status }] }`	Closest myclimate option to the unified segment model. Maps root totals plus `segments[]`.	High
GoClimate	Flight footprint	`GET /v1/flight_footprint`	Query params: `segments[n][origin]`, `segments[n][destination]`, `cabin_class`, `currencies[]`.	`{ footprint, offset_prices:[{ amount, currency, offset_url, locale }], details_url? }`	Returns one total plus offset prices. Segment-level output is not exposed.	High
C-Level	Flight offset quote / calculation	`POST /v1/calculate/flight`	`{ IataCodes, IsReturn?, Passengers, Class?, Type?, AircraftModel?, Reference, CurrencyCode? }`	`{ Co2PerPerson_kg, Passengers, FlightClass, TotalDistance_Km, TotalDistance_Miles, PerPersonDistance_Km, PerPersonDistance_Miles, PerPersonPrice, QuoteId, Co2Total_Kg, Co2Total_Tonne, TotalPrice, CurrencyCode, QuoteExpiry, MetaData, ShortDescription }`	Quote/offset-oriented provider. Needs `quote`, `offset`, `perPassenger`, and `perPassengerPrice` fields in unified model.	High
KlimaLink	Flight calculation	`POST /api/v1/calculateEmission`	`{ flightActivities:[{ index, departure/arrival OR flightNumber/flightDate, aircraftType?, airline?, passengerCount?, flightCount, travelClass? }] }`	`{ flightActivities:[{ index, status, emissionKgCO2e, errors, type }], status, emissionKgCO2eTotal }`	Strong batch/list model. Maps cleanly to root total plus `segments[]` with per-segment status/errors.	High
KlimAPI v2	Standalone flight calculation	`POST https://api.klimapi.com/v2/calculate`	`{ calculation_options:[{ type:"travel-air", activity:"flights", specification:"short-haul	long-haul	average", detail:"economy_class	business_class
KlimAPI v1	Standalone flight calculation	`POST https://api.klimapi.com/v1/calculate`	`{ calculation_options:[{ type:"flight", departure, destination, travel_class:"average	economy	premium	business
Climatiq	Travel flight distance	`POST https://preview.api.climatiq.io/travel/v1-preview3/distance`	`{ travel_mode:"air", origin:{ iata }, destination:{ iata }, year?, distance_km?, air_details? }`	`{ co2e, co2e_unit:"kg", co2e_calculation_method, distance_km, origin, destination, direct_emissions, indirect_emissions, notices, source_trail }`	One-way, one passenger per call; preview feature. Maps well to root total plus metadata/source trail.	High / preview
Carbon Interface	Flight estimate	`POST https://www.carboninterface.com/api/v1/estimates`	`{ type:"flight", passengers, legs:[{ departure_airport, destination_airport }] }`	`{ data:{ id, type:"estimate", attributes:{ passengers, legs, distance_value, distance_unit, estimated_at, carbon_g, carbon_lb, carbon_kg, carbon_mt } } }`	Good fit for root total plus request-leg echo.	High
TravelCO2	Transport emissions, distance-based flight approximation	`POST https://travelco2.com/api/v1/transport`	`{ vehicle:{ type, fuel:{ type } }, distance, people, language? }`; for flights, use flight vehicle keys such as `flight-regular-economy` plus fuel such as `jetfuel`. Distance is in meters.	`{ distance, people, ways, co2e, co2e_pp, vehicle:{ vehicle_count, type, title, fuel:{ type, title } }, type, title }`	Usable for `travel.flight.estimate_emissions.distance` only. Does not resolve airport pairs. Connector must provide/derive distance.	Medium / distance-only
CarbonTracer	Routing-based flight estimate	`GET https://api.carbontracer.uni-graz.at/routing/{apikey}/{typ}/{start}/{dest}` plus optional `/options={opts}`	Path params: `typ`, e.g. `flight-economy`, `flight-business`, `flight-firstclass`; `start`; `dest`; option `airports` for flight routing.	`{ response:{ success, warning, data:{ startLocation, endLocation, distanceDirect, distanceRoute, co2eq, occupancy, co2eq_occupancy, unitco2eq, unitdistance, requestType, ... } } }`	Good path-GET provider. Maps route distance, per-occupancy emissions, and location metadata.	High
CarbonTracer	Distance-only estimate	`GET https://api.carbontracer.uni-graz.at/co2only/{apikey}/{typ}/{distance_km}`	Path params: `typ`, `distance_km`.	`{ response:{ success, warning, data:{ distance, co2eq, unitco2eq, unitdistance, requestType } } }`	Useful fallback if distance is already known.	High
IBM EIS Carbon Accounting	Transport / transportation and distribution	`POST https://foundation.agtech.ibm.com/v2/carbon/carbon/transportation_and_distribution` or possibly `/carbon/transportation_and_distribution` depending base URL normalization.	Context object plus `activityData:{ typeOfActivityData, vehicleType, distanceTravelled, numberOfPassengers?, totalWeightOfFreight?, unitOfMeasurement, fuelUsed?, fuelAmount?, unitOfFuelAmount? }`.	Response schema not visible in accessible docs.	Requires separate JWT flow via `Auth/GetBearerForClient`. Can model distance-based flight/transport, but response mapping remains provisional.	Partial

Normalization notes

Endpoint now always includes method and path/URL.
Request shape and Response shape are concise pseudo-JSON, not full schemas.
Mapping / use notes replaces the earlier mixed “Notes” and “Mapping consequence” columns.
Status makes uncertainty explicit: High, Medium / legacy, Medium / distance-only, High / preview, or Partial.
Duplicate Atmosfair, C-Level, and KlimaLink rows were merged.
Non-flight Atmosfair rows were kept because they influence the future domain-neutral schema.