How to Upgrade Data Versions

Climatiq versions the underlying data that powers its calculations. This means that you will need to upgrade your data version occasionally to use the latest data.

This guide assumes that you know the basics of how data versioning works and that you are looking to upgrade your data version. If you are not quite sure what data versioning is, you can read more about it here.

Endpoints that perform calculations such as flights, intermodal, or computing do not accept a data version at all. For these endpoints, you do not need to worry about data versions unless you provide a selector to override parts of the calculation.

For the endpoints that do accept a selector with a data version, here is what you need to take into account:

Upgrading Minor Versions

If you are on a full version, such as 1.2, and wish to upgrade to the latest minor version, you can do so relatively safely by changing the last part of the number to the latest data version.

This should be a painless process without much risk of breaking, as minor versions only ever add new emission factors and never remove any.

If you are already on a major-compatible version such as ^1, you are already receiving the latest emission factor. ^1 always corresponds to major version 1 with the latest minor version, and there is no need to update minor versions explicitly.

If you don't require reproducible calculations, we recommend you use only a major-compatible version, such as ^1, or ^2 and automatically receive minor updates.

Upgrading Major Versions

If you want to upgrade a major version, some emission factors might be removed. Our recommended process for upgrading major versions is as follows:

• Always upgrade one major version at a time, even if you want to upgrade multiple data versions, such as from ^0 to ^3.
• Always upgrade to a major-compatible version instead of a full version to start off with. In this example, you would upgrade to ^1.
• Refer to the data changelog for the major version you are upgrading to. See if there are any changes that will impact you.
• Test your application to see if it still works as expected.
• Optional: Then upgrade to the next major-compatible version if you still need to. In this case, that would be ^2.
• Optional: If you want to lock down to a specific full version, such as 2.2, you can do this at the end. We recommend not specifying a full version where the minor version is smaller than the major version. So 1.1 and 2.5 are good, but 2.1 is not advised.