Sync Product co2api-apis-request-response from project files
50
Product co2api-apis-request-response.-.md
Normal file
50
Product co2api-apis-request-response.-.md
Normal file
@@ -0,0 +1,50 @@
|
||||
<!-- codex-wiki-sync:4e8b42ddef07e0bae3421529 -->
|
||||
|
||||
> 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 `FlightByFlightNumber`and`FlightByDistance` 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][1]) |
|
||||
| **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 | Docs][2]) |
|
||||
| **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][4]) |
|
||||
| **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][4]) |
|
||||
| **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][5]) |
|
||||
|
||||
[1]: https://www.climatiq.io/docs/api-reference/travel "Travel - Climatiq API Reference - Automated Carbon Emission Calculations"
|
||||
[2]: https://docs.carboninterface.com/?utm_source=chatgpt.com "Carbon Interface | Docs"
|
||||
[4]: https://carbontracer.uni-graz.at/api-doc "CarbonTracer"
|
||||
[5]: https://www.ibm.com/docs/en/SSRQLT_suite/EIS_Carbon_Accounting_API_developer_guide_v1.0.pdf "Carbon_API_documentation_v4"
|
||||
|
||||
|
||||
| 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. |
|
||||
Reference in New Issue
Block a user