API Reference
Data Versioning

Data Versioning

Climatiq uses a major.minor versioning system for its emission factors, allowing you to choose between up-to-date factors and consistent results. When using a Selector with an activity ID, you must provide a data_version field.

Major and Minor Versions

Modifications to emission factors involve marking the old factor as deprecated and adding a new one. Minor versions include both deprecated and updated factors, whereas major versions remove deprecated factors.

Data Versions Endpoint

Climatiq provides a Data Version endpoint to help you find the latest major and minor data versions. Learn how to use it here

Upgrading Versions

We recommend you update your data version periodically. There are two ways you can upgrade your data version:

  • Incrementing the minor version: This may change the matched emission factor for your selector, but won't cause a previously working selector to return 0 results as no emission factors are removed in minor versions.
  • Incrementing the major version: This ensures you use updated factors but may lead to 0 results if you were previously matching on a deprecated emission factor.

Choosing the Right Data Version

  • For up-to-date emission factors, use the latest major-compatible version. This is currently: ^10
  • For consistent results, choose the latest major-minor version. This is currently: 10.10
  • If unsure, opt for the latest major-compatible version. This is currently: ^10
Data Versioning References

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.

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 or need clarification, please don't hesitate to reach out.

Finding the Latest Data Version

GET We offer an API endpoint to help you find the latest major and minor data versions.

curl --request GET \
--url https://api.climatiq.io/data/v1/data-versions \
--header "Authorization: Bearer $CLIMATIQ_API_KEY"

Response

{
"latest": "10.10",
"latest_major": 10,
"latest_minor": 10
}

Using this response, you can:

  • Use the value of latest_major with a caret (^) in front of it if you want the latest major-compatible version.
  • Use the value of latest if you want the latest major-minor data version.
  • Use the latest_minor to get updates for a previous major version you are using.