Data Versioning
Climatiq regularly releases updates to it's database of emissions factors, each release consists of additions, deletions and updates. In order to give you control over when you take advantage of those data releases, Climatiq uses a data versioning system. When using a Selector with an activity ID (which is mostly only applicable to the estimate endpoint) and when using search, you must provide a data_version field.
Data versioning is a complex topic, and this page only provides a brief overview. We highly recommend reading the data versioning guide for an in-depth explanation of how and why we implement data versioning at Climatiq.
We have simplified our data versioning based on user feedback. The previous format used major.minor, and was usually seen with the same data release number for major and minor, eg. 16.16. This format still works, but we recommend using the new fixed data version format below. Some deprecated fields in the API still return the old version.
This simplification means removal of functionality to control when to adopt non-breaking changes - please contact us (opens in a new tab) if you have a use for this advanced functionality.
Choosing the right data version
- For repeatable results, choose the latest fixed version. This is currently:
18 - For up-to-date emission factors, use the latest dynamic version. This is currently:
^18 - If unsure, opt for the latest dynamic version. This is currently:
^18
See section in the data versioning guide for more help with choosing which type of version to use or upgrading data versions.
You might also be interested in our data version changelogs to stay informed about changes between versions and receive assistance with migration.
If you have further questions, need clarification or need more control over when you adopt non-breaking changes, please don't hesitate to reach out.
Fixed data versions
Using a fixed data version involves just providing a data release number, eg. 17, which is one of the data releases in our data changelog. This locks your request into using the data from that release and updates to our data won’t affect your results, enabling you to make repeatable calculations. If you don’t require repeatable calculations, we recommend you use a dynamic data version.
Dynamic data versions
Using a dynamic data version involves providing a data release number prefixed with ^, eg. ^17. When used, you get a view of our data which is compatible with the fixed version of that data release, but also contains any updates that won’t break your request. This enables automatically using the latest data, but keeps you in control of when you adopt breaking changes by bumping the compatible data release number.
Finding the latest data version
We offer an API endpoint to help you find the latest data version programmatically.