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 called Air Freight
• Rail Transport is now called Rail Freight
• Road Transport is now called Road Freight
• Sea Transport is now called Sea Freight
• Transport Services is now called Freight Services

These categories have been merged

• Vehicle has been merged into Vehicles
• Food and Non-Alcoholic Beverages has been merged into Food/Beverages/Tobacco
• Alcoholic Beverages and Tobacco has been merged into Food/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.