Beta v3 Migration Guide
Climatiq's Beta v3 release comes with a significant number of improvements such as:
- API endpoints providing all available GHGs as well as total CO2-equivalent
- Where pre-calculated CO2e values are not provided by the source, the API can provide these - according to either IPCC AR4 or AR5 as requested
- Freight and travel flights endpoints with automatic emission factor selection.
It should be noted that the v3 Beta comes with some backwards-incompatible changes.
beta2.api.climatiq.io
will remain available, but will receive no new updates. You can continue to use beta2.api.climatiq.io
until you're ready to migrate.
The base url for the new API is beta3.api.climatiq.io
.
Breaking changes in Beta v3:
Please be aware of the following things that might cause your implementation to break in the migration from Beta v2 to Beta v3.
New estimate endpoint response
The /estimate
endpoint response has changed. Most notably, the fields describing the emission factors used for the calculation are now nested inside an object.
Below you can see the difference between the Beta v2 and the Beta v3 response, for the same emission factor.
Beta v2 response
{ "co2e": 183.3, "co2e_unit": "kg", "id": "accommodation_type_hotel_stay", "source": "BEIS", "year": "2021", "region": "MV", "category": "Accommodation", "source_lca_activity": "unspecified"}
Beta v3 response
{ "co2e": 183.3, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "id": "accommodation_type_hotel_stay", "source": "BEIS", "year": "2021", "region": "MV", "category": "Accommodation", "source_lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 183.3, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }}
The Digital unit has been renamed to Data.
Instead of providing size
and size_unit
, in Beta v3 you must provide data
and data_unit
Before (Beta v2)
{ // ...Rest of /estimate request "parameters": { "size": 1, "size_unit": "GB" }}
Now (Beta v3)
{ // ...Rest of /estimate request "parameters": { "data": 1, "data_unit": "GB" }}
The Spend unit has been renamed to Money.
Instead of providing spend
and spend_unit
, in Beta v3 you must provide money
and money_unit
Before (Beta v2)
{ // ...Rest of /estimate request "parameters": { "spend": 1, "spend_unit": "usd" }}
Now (Beta v3)
{ // ...Rest of /estimate request "parameters": { "money": 1, "money_unit": "usd" }}
The Amount unit has been renamed to Number.
Instead of using amount
in your request, in Beta v3 you must use number
Before (Beta v2)
{ // ...Rest of /estimate request "parameters": { "amount": 1 }}
Now (Beta v3)
{ // ...Rest of /estimate request "parameters": { "number": 1 }}
The AmountOverTime unit has been renamed to NumberOverTime.
Instead of using number
instead of amount
.
Before (Beta v2)
{ // ...Rest of /estimate request "parameters": { "amount": 1, "time": 1, "time_unit": "h" }}
Now (Beta v3)
{ // ...Rest of /estimate request "parameters": { "number": 1, "time": 1, "time_unit": "h" }}
The Unit Types for some emission factors have been changed
The storage and the memory CPU emission factors now use the new unit DataOverTime. If you use these units, you will have to explicitly specify a time, where previously the calculation always was for 1 hour.
Some Unit Types have been removed
The FlightDistance
, and WeightOverFlightDistance
units have been removed.
Please use the new flights endpoints for the same functionality, which should support the same use cases much better, such as by automatically selecting appropriate emission factors for a route.
Category names updated
Some sector and category names have been updated to better reflect the contents of them.
These categories have been renamed
Air Transport
is now calledAir Freight
Rail Transport
is now calledRail Freight
Road Transport
is now calledRoad Freight
Sea Transport
is now calledSea Freight
Transport Services
is now calledFreight Services
These categories have been merged
Vehicle
has been merged intoVehicles
Food and Non-Alcoholic Beverages
has been merged intoFood/Beverages/Tobacco
Alcoholic Beverages and Tobacco
has been merged intoFood/Beverages/Tobacco
The persistence option has been removed
We have removed the ability to specify whether calculations are persisted on Climatiq's servers; instead, all calculations will be persisted.
The metadata option has been removed
We have removed the ability to specify metadata, such as which scope a calculation belongs to.