add-ideas/emission-api-lib
1
0
Fork 0
Code Issues 37 Pull Requests Actions Packages Projects Releases Wiki Activity

Sync Product co2api-apis-request-response-new from project files

zemion
2026-07-06 14:29:27 +02:00
parent 0a99d11699
commit b01c03e028
1 changed files with 41 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
Product co2api-apis-request-response-new.-.md Normal file

@@ -0,0 +1,41 @@
<!-- codex-wiki-sync:ac7946faaaddb03e913d63ec -->
> 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 | premium_economy_class | first_class | average", departure, destination, return_trip, passengers }], fractional_digits? }`; passenger-distance variant uses `{ value, unit:"passenger.kilometers" }`. | `{ kgCO2e, calculation_id, results:[{ type, activity, specification, detail, value, unit, kgCO2e, emission_factor_id, emission_factor_last_updated }] }` | Best KlimAPI version. Maps cleanly to `EmissionCalculationResult.total.co2eKg`, `quote.id`, and segment metadata. | **High** |
| **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, return_trip }], fractional_digits? }`; also has flight-number and distance schemas. | `{ kg_amount, calculation_id, results:[{ result, type, ...provider-dependent details }] }` | Usable but outdated. Needs separate XML because response shape differs from v2. | **Medium / legacy** |
| **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.