Caching emission factor data

Some teams choose to pull emission factors from Climatiq into their own data store rather than querying the Search endpoint on every request. This pattern reduces API calls, lowers latency for high-frequency lookups, and lets you run your own review process when factors change each month.

This guide explains how to build and maintain that local cache: how to pull factors, what to store, and how to detect changes when Climatiq publishes a new data release.

Pulling factors via Search

The Search endpoint lets you pull emission factors from Climatiq’s database using optional filters. It returns up to 500 factors per API call, and via pagination you can iterate through the full database or any filtered subset.

When building an initial cache, first call the data version endpoint to get the current latest_release number, then use that as a fixed data_version in your Search requests. This ensures all factors in your store come from the same release and are internally consistent. See the data versioning guide for a full explanation of fixed vs. dynamic versions.

See the Search endpoint reference for the full request and response format, including all available filters.

Pagination

Search returns results in pages. Add a page parameter to iterate through the full result set:

# First page (page parameter defaults to 1)
GET https://api.climatiq.io/data/v1/search?activity_id=electricity-supply_grid*&data_version=34&results_per_page=500
 
# Second page
GET https://api.climatiq.io/data/v1/search?activity_id=electricity-supply_grid*&data_version=34&results_per_page=500&page=2

Continue incrementing page until current_page equals last_page in the response.

Filtering to what you need

Use the available filters to pull only the factors relevant to your application:

• activity_id with a wildcard (e.g. electricity-supply_grid*) to match a category of activities
• region to limit to specific geographies
• unit_type to limit to factors that match your input units
• source to limit to a specific dataset

Pulling a narrower set of factors reduces storage requirements and makes the set of changes to review each month smaller.

Refreshing monthly

Generally every month, Climatiq releases a new version of the emission factor database where new factors are added, existing factors are updated, and old factors may be removed. There are two ways to stay informed when a new release lands:

• Data release changelogs: A full breakdown of every change in each release, including which factors were added, updated, or removed.
• Release notes emails: Subscribe at climatiq.io/changelog-signup  to receive release notes directly.

Not every factor changes every month. Some factors (such as national grid electricity factors tied to annual government publications) update once a year or less frequently. Review the changelog for each release rather than assuming all factors in your cache have changed.

How to detect changes

Each factor returned by the Search endpoint includes a data_version object that describes its status relative to the latest release. When you query a previous (static) data version, this field tells you whether that factor has since been updated or removed:

• up_to_date: the factor has not changed since the version you queried. No action needed.
• replaced: a newer version of this factor exists. The replaced_by field provides the id of the replacement factor, and replaced_in gives the release number where the replacement took effect.
• removed: this factor has been removed from the database without a replacement. The removed_in field gives the release number where it was removed.

See the Search endpoint reference for the full data_version object schema.

Recommended monthly refresh process

1. Check the data release changelog for the new version to understand what has changed before taking any action.
2. Re-query the Search endpoint using your cached data_version number (e.g. data_version=34). The API automatically compares each factor from that version against the current latest release and returns a data_version.status field on each result — you do not need to compare versions manually. For each factor, inspect data_version.status and update your local database:
   • replaced: record the replaced_by ID and replaced_in release number against that factor in your local database.
   • removed: mark the factor as removed. It can no longer be used for new calculations.
   • up_to_date: no action needed.
3. Handle removed factors. For factors marked as removed in step 2, remove them from your cache. If a removed factor is tied to active calculations or submitted reports, retain it and flag it for human review rather than deleting it.
4. Pull the new data version and add the delta to your local database. The delta covers two parts:
   1. Replacement factors (fetch using the replaced_by IDs recorded in step 2) and;
   2. Newly added factors in this release that do not yet exist in your cache.
5. Flag any replaced factors tied to active calculations or submitted reports for human review before applying the update.

Why factors are removed or updated

Climatiq removes or updates emission factors when:

• A source publishes corrections or updates to the underlying data, e.g. as UK BEIS does in each of their annual updates
• Climatiq restructures metadata such as activity_id to provide more accurate scope or context (all updates change the factor’s id)
• A source deprecates the dataset entirely
• Climatiq’s science team deprecates factors due to data quality issues

Note that activity_id values can change between releases when Climatiq restructures factor metadata. If a factor appears missing after a release, check data_version.status before treating it as a deletion: if the factor has been re-categorized, it will appear as replaced and the replaced_by field will point to the new factor.

Deprecations are documented in the data release changelogs.

What to store from each factor

Store the complete response for each factor. Emission factor records are compact, and retaining all fields gives you everything needed for calculations, matching factors to your internal records, and reproducing historical results without additional API calls.

Two fields are particularly important for the refresh process:

• id: uniquely identifies this exact version of a factor. Use it to identify and retrieve replacement factors during a refresh.
• data_version number: the version number you used when pulling these factors (e.g. 34). Climatiq does not return this in the factor response, so record it alongside each factor. You need it to query your cache against the correct static version at refresh time.

Integrating with your existing data process

Most teams already have an established process for maintaining their data stores: versioning records, running change reviews, or routing updates through an approval workflow. The guidance in this article is meant as a starting point, but needs to be adapted to your own processes.

Before designing a refresh strategy, consider how emission factor data is currently versioned and stored in your system. The monthly changes from Climatiq should feed into whatever review or approval workflow you already have in place. For factors tied to submitted or audited reports, changes should go through that existing review process rather than being applied automatically.

Supporting resources