Energy v1 General Availability (GA)

• Climatiq has released the first General Availability (GA) version of the energy feature.
• The GA version of the feature has passed a validation audit confirming compliance with the requirements of ISO 14067 and GHG Protocol - Product Life Cycle Accounting & Reporting Standard. Please see the Climatiq Trust page (opens in a new tab) for more details.
• This is the changelog & upgrade guide for the GA version. See our API versioning guide for how API versioning works at Climatiq.
• This document lists the changes between v1-preview1, v1-preview2 and v1 (GA).

Changes between v1-preview2 and v1 (GA)

The GA version of energy is equivalent to the v1-preview2 version except for the removal of the "Advanced Audit Trail" functionality. This means that audit_trail is no longer returned in the response.

For users that had access, the advanced audit trail feature provided a detailed view into the calculations Climatiq performed. This was meant to allow users to verify that the calculations were accurate and methodologically valid.

This did not prove as easy to work with for our end-users as we had hoped, so we have now removed it. The source trail feature is available to all users to view details about what data underpins the calculation. If you are being audited and you need detailed methodological documents, please reach out (opens in a new tab).

In addition, users can gain assurance over the methodological validity of our calculations through the validation audit (see above).

Changes between v1-preview1 and v1 (GA)

Backported non-breaking feature additions

Since v1-preview1 we have added several new features. These were backported to preview1 as well, so you might already be using them:

• We have added electricity support for 17 new countries to the core dataset, bringing the total available without an IEA license to 63. An IEA license brings the number to 149.
• We now also support more flexible region selection in electricity, so in addition to a country code eg. DE, we also support subdivisions, eg. DE-BB, UN/Locodes, eg. DE-BER and ZIP codes in the US, eg. US-12345. In each of these cases we will fallback to the best surrounding region that we have data available for. This is either a sub-grid area, state or country.
• Limited support for biogenic CO₂ reporting has been added to the fuel feature, with a new field co2_biogenic.
• We regularly update the data used by these endpoints and review and improve the methodology - these changes don't require any action to take advantage of.

API Changes (Request)

The request and responses between v1-preview1 and v1 are quite similar, with some notable changes that might affect you:

Fuel endpoint fuel_type normalization

We undertook a major normalization of fuel types as part of data release 16, this makes it easier to switch between units and regions and makes for better coverage. These fuel_types are already available and suggested by default in v1-preview1, but in v1-preview2 the fuel_types from before normalization are removed and stop working.

If you hardcode fuel_types in your application, you should test those out with the new version to see if they are working, or get the new list of fuel_types, see choosing a fuel_type.

Electricity endpoint supplier name updates

A few supplier names have changed, if you hard code these in your application, you should test they still work or get the new list of suppliers, see choosing a supplier.

loss_factor not allowed on grid electricity components

For electricity components where connection_type: grid, we no longer allow you to provide a loss_factor as we always use the loss factor of the region. We accepted and ignored this parameter in v1-preview1, but providing it is now an error.

API Changes (Response)

The response format has been updated to match changes which we have already applied in some other endpoints.

• co2e_calculation_method replaces calculation_method, it has a new format which is more future-proof and represents our interest in supporting other CO2-equivalences in the future. The old calculation_method used to return ar4, ar5 or ar6 and the new values co2e_calculation_method can return are ipcc_ar4_gwp100, ipcc_ar5_gwp100, ipcc_ar6_gwp100 or ipcc_mixed_gwp100 . AR5 or AR6 methods, as we didn't have a way to indicate a mixed calculation. Mostly this is a naming change, but it also introduces a new option: ipcc_mixed_gwp100. While Climatiq attempts using a consistent method for calculations, this is not always possible. ipcc_mixed_gwp100 is returned in cases where we have had to mix calculation methods to provide an estimate.

• The deprecated source_data has been removed, all the data it provided can be seen in a different format in source_trail.

• A new field constituent_gases gives you a breakdown of which gases contributed to the CO₂e total, where that data is available from sources. This is the case for all IEA consumption estimates, and some national sources used in each of the endpoints.

• The audit_trail field is no longer returned. See the changes from preview2 to v1 for more details.

Methodological changes

• Calculation method can now be mixed, enabling us to use a few more national sources which provide co2e data only using AR5 or AR6.
• The region CA-PE is no longer supported for electricity. The underlying data was removed due to data quality issues.
• Some emission factors with incorrect applicability years has been removed.
• For electricity calculations we now use a fall-back calculation method for well-to-tank emissions where there are no available well-to-tank emission factors.