Beta4 Migration Guide

Climatiq’s Beta v4 release comes with a significant number of improvements such as:

• Versioning of emission factors to allow you to decide how much stability and freshness you want to opt into for the underlying data used to perform your calculations.
• The AR6 calculation method, which reflects the newest scientific consensus.
• Improved handling of how we treat the year parameter.
• Updated default data quality flags
• Switched our source for monetary exchange rates to the UN treasury, improving the accuracy and reliability of our currency exchange data.

For more information on the scope of the changes, see the release notes. This guide will try to guide you step-by-step on how to migrate from beta3 to beta4.

Base URL Change

At the end of this section, you should be using the beta4 API, even though some of your calls might result in errors.

• You should change your base URL from beta3.api.climatiq.io to beta4.api.climatiq.io.

Update Your Code to Take the New API Structure into Account

At the end of this section, most of your API calls should work, but still might not find any emission factors.

• The "emission_factor" and "constituent_gases" returned when estimating can now be null, unless you have access to our audit trail feature. You should change your code to account for the fact they are possibly null. For more information, see audit trail
• You should update "year" to be an integer instead of a string, both in requests and responses.
• You can no longer provide a string instead of a full selector for an emission factor. If you have queries like "emission_factor: "my_activity", you should change it to: "emission_factor: {"activity_id": "my_activity"}. This behavior has been deprecated and undocumented for a while.
• The id field has been renamed to activity_id. If you provide a selector with id, please rename it to activity_id. If you read id from the API responses, you should instead read activity_id.
• The id field now refers to the old uuid field instead of the activity ID. The uuid field has been deleted. If you use or read the uuid field, please use id instead.
• lca_activity has been renamed to source_lca_activity.
• Our error structure has changed. If you rely on programmatically parsing errors, you should update your code to take the new structure into account.
• When performing /search queries, the unit_type returned is a string instead of an array.
• If you use endpoints that require a selector, you must add the mandatory data_version parameter. The API will throw an error if you need to supply a data_version. We recommend you use ^0 to start off with, as that will leave you on the beta3 data version while you perform the migration. You can then update to the latest data_version later in the process.

Specific Endpoints

This section list the changes you will need if you use some of our more specific endpoints. You will only need to make changes here if you use one of these specific API endpoints.

Cloud Computing:

• The cloud computing endpoints are now add-ons. You will need to contact Climatiq to get access.
• The cloud metadata endpoint now returns one list of regions instead of separate lists for CPU, memory, and storage. You should update your API with the new response model.
• The Azure cloud regions central_india, south_india, and west_india are no longer usable. Please use india_central, india_south, and india_west instead.

Freight Flights:

• The freight flight emission endpoint has been removed. Please use the GLEC-certified intermodal freight endpoint instead.

Emission Factors Endpoints:

• The metadata endpoints such as /emission-factors/sources and emission-factors/lca_activities no longer exist. Please use /search instead. The possible_filters return value will provide the same values as the old endpoints used to.
• The deprecated /emission-factors endpoint has been removed. Please use the /search endpoint instead.

Classification Endpoint:

• This endpoint is now an add-on. You will need to contact Climatiq to get access.
• The classification endpoint has been updated to use a later data version, which comes with some changes. If you only provide a classification code and scheme you won’t need to do anything. However if you provide more values, such as year or lca_activity, you might in rare cases need to change your queries to work with the new data version.
  • If that is the case, and your queries no longer return results, follow the instructions further down below for the classification endpoint as well.

Custom Mappings:

• This endpoint is now an add-on. You will need to contact Climatiq to get access.

Update Years

After completing this section, most of your queries and API calls should work again.

If you explicitly query for year in your selectors, you might not get any results. This is because we previously used year to indicate the year when the source published the data, but it should more accurately represent the year for which the source states the data is valid. These are not always the same value, and we have updated our logic accordingly. If you do not filter explicitly on year, you do not need to make any changes.

If you do filter explicitly on year, you will need to test your queries. About 10,000 emission factors are affected by this change, so there is a high likelihood that you may be impacted.

If you use one of the below sources, you should change year_released in the below table to year_valid_from:

If this replacement does not resolve the issue, try removing the year parameter from your query to stop filtering by year. Observe the year returned by the API, and use that as the year in your selector.

Update Data Quality Flags

After completing this section, all of your queries and API calls should work again.

We have updated the list of default data quality issues we allow. Previously, we only excluded suspicious_homogeneity by default and allowed everything else for backward compatibility reasons. Now, we allow by default:

• partial
• notable_methodological_variance

To revert to the previous behavior, add "allowed_data_quality_flags": ["erroneous_calculation", "partial", "notable_methodological_variance", "self_reported"] to your selectors or the query-string equivalent to your /search queries.

Although this is helpful for determining whether your query cannot find emission factors due to data quality issues, we do not recommend applying this change to all queries unless you are certain you want these emission factors with quality concerns.

Update to the Newest Data Version

After completing these steps, your code should be using the newest version of the API, with data version ^0. The next step is updating to the latest data. Data release 1 includes more than 6,000 corrections to emission factors, as do each of the releases afterwards, and we strongly recommend upgrading. To learn how to do this, consult the data version migration guide and the data release changelog.

If you encounter difficulties during the upgrade process, please do not hesitate to contact us for assistance.