1

Product co2api-apis-request-response

zemion edited this page 2026-07-06 14:29:23 +02:00

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

---

Provider	Endpoint	Request JSON / params	Response JSON
calco2la.to	POST /api/flight or planned /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:[...] }
Atmosfair	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:[...] }
Google TIM direct	POST /v1/flights:computeFlightEmissions	{ flights:[{ origin, destination, operatingCarrierCode, flightNumber, departureDate:{year,month,day} }] }	{ flightEmissions:[{ flight, source, emissionsGramsPerPax:{first,business,premiumEconomy,economy}, ... }], modelVersion }
Google TIM Scope 3	POST /v1/flights:computeScope3FlightEmissions	{ flights:[{ departureDate, cabinClass, origin?, destination?, carrierCode?, flightNumber?, distanceKm? }], modelVersion? }	{ flightEmissions:[{ flight, wtwEmissionsGramsPerPax, ttwEmissionsGramsPerPax, wttEmissionsGramsPerPax, source }], modelVersion }
myclimate 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? }
myclimate v2	POST /v2/flight_calculators.json	v1 plus aircraft_type_leg_1, aircraft_type_leg_2	same general response as v1
myclimate bulk	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, co2eq_kg, km, status, ... }] }
GoClimate	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? }
C-Level	POST /v1/calculate/flight	{ IataCodes, IsReturn?, Passengers, Class?, Type?, AircraftModel?, Reference, CurrencyCode? }	{ Co2PerPerson_kg, Passengers, FlightClass, TotalDistance_Km, PerPersonPrice, QuoteId, Co2Total_Kg, Co2Total_Tonne, TotalPrice, CurrencyCode, QuoteExpiry, MetaData, ShortDescription }
KlimaLink	POST /api/v1/calculateEmission	{ flightActivities:[{ index, departure/arrival OR flightNumber/flightDate, aircraftType?, airline?, passengerCount?, flightCount, travelClass? }] }	{ flightActivities:[{ index, status, emissionKgCO2e, errors, type }], status, emissionKgCO2eTotal }

Provider	Request model	Response model	Mapping consequence
Atmosfair flight	POST /api/emission/flight; body includes accountId or username, password, optional calculationMethod, and flights[]. Each flight can use either departure/arrival or flightNumber/departureDate, plus passengerCount, flightCount, travelClass, charter, aircraftType. Atmosfair supports multi-hop by sending one flight element per segment.	Root object with status, errors, offsetInEUR, co2, co2WithoutRfi, cruiseAltitude, distance, distanceInCriticalAltitudes, fuelInLiter, and flights[].	Fits very well into EmissionCalculationResult with nested segments.
Atmosfair rail / hotel / car	Separate endpoints /api/emission/rail, /api/emission/hotel, /api/emission/carrental; rail supports stations or distance, hotel supports overnights or price models, car rental supports distance, price, or days.	Shared simple response pattern: status, errors, offsetInEUR, co2; car response follows hotel pattern.	Confirms the unified schema should be domain-neutral, not flight-only.
C-Level flight	POST /v1/calculate/flight; body schema FlightOffset. Fields from description: IataCodes[], IsReturn, Passengers, Class, Type, AircraftModel, CurrencyCode, UrlReferer, Personalisation, SendCertificate, CertificateSendEmail.	Response schema FlightOffset; exact JSON fields still not included in the extract.	Request can be mapped now; response mapping needs the schema definition for Balance.Core.Model.Api.Responses.FlightOffset.
KlimaLink flight	POST /api/v1/calculateEmission; bearer token; body { flightActivities: [...] }. Each activity can use either departure/arrival optionally with airline/aircraftType, or flightNumber/flightDate; plus index, flightCount, passengerCount, travelClass.	Root: flightActivities[], status, emissionKgCO2eTotal. Each item: index, status, emissionKgCO2e, errors, type.	Very good batch/list model; maps cleanly to root total + segment results with per-segment status/errors.

Provider	Endpoint	Request JSON	Response JSON	Notes
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 /premium_economy_class / first_class / average", "departure": "...", "destination": "...", "return_trip": true, "passengers": 1 } ], "fractional_digits": 2 }or passenger-distance variant with{ "type": "travel-air", "activity": "flights", "specification": "...", "detail": "...", "value": 1234, "unit": "passenger.kilometers" }	{ "kgCO2e": number, "calculation_id": string, "results": [ { "type", "activity", "specification", "detail", "value", "unit", "kgCO2e", "emission_factor_id", "emission_factor_last_updated" } ] }	Best KlimAPI version for your provider XML. Maps cleanly into EmissionCalculationResult.total.co2eKg and segment/result metadata.
KlimAPI v1 — standalone flight calculation	POST https://api.klimapi.com/v1/calculate	{ "calculation_options": [ { "type": "flight", "departure": "...", "destination": "...", "travel_class": "average / economy / premium / business/ first", "passengers": 1, "return_trip": true } ], "fractional_digits": 0 }; v1 also has FlightByFlightNumberandFlightByDistance schemas.	{ "kg_amount": number, "calculation_id": string, "results": [ { "result": number, "type": "...", "...Additional Details": provider-dependent } ] }	Usable, but outdated. Response shape differs from v2, so it needs a separate provider XML.

Provider	Endpoint	Request shape	Response shape	Notes
Climatiq Travel v1-preview3	POST https://preview.api.climatiq.io/travel/v1-preview3/distance	{ travel_mode:"air", origin:{iata:"FRA"}, destination:{iata:"SFO"}, 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; air travel includes RF multiplier; preview feature requires opt-in. (Climatiq)
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 } } }	Supports passenger flight estimates based on airport legs and passengers. ([Carbon Interface
CarbonTracer routing	GET https://api.carbontracer.uni-graz.at/routing/{apikey}/{typ}/{start}/{dest} and optional /options={opts}	Path params: typ e.g. flight-economy, flight-business, flight-firstclass; start, dest; options include airports for flight routing	{ response:{ success, warning, data:{ startLocation, endLocation, distanceDirect, distanceRoute, co2eq, occupancy, co2eq_occupancy, unitco2eq, unitdistance, requestType, ... } } }	Free API key after registration; 40 requests/min and 2000/day. (carbontracer.uni-graz.at)
CarbonTracer distance-only	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 when distance is already known. (carbontracer.uni-graz.at)
IBM EIS Carbon Accounting Transport	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 PDF	IBM docs require JWT generation via Auth/GetBearerForClient, then production URL https://foundation.agtech.ibm.com/v2/carbon; transport endpoint calculates business travel, commuting and freight emissions. (IBM)

Provider	Endpoint	Request shape	Response shape	Notes
TravelCO2 Transport API	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, flight-regular-business, etc., plus fuel key such as jetfuel. Distance is in meters.	{ distance, people, ways, co2e, co2e_pp, vehicle:{ vehicle_count, type, title, fuel:{ type, title } }, type, title }	This is now usable for travel.flight.estimate_emissions.distance, provided the connector can supply/derive distance in meters. It does not calculate from airport pairs.