Mapping Agent v1 General Availability (GA)

Mapping Agent used to be called Autopilot. If you are migrating, you might have older URLs for e.g. /autopilot/v1-preview4/*.

Climatiq has released the first General Availability (GA) version of the Mapping Agent feature. The GA feature comes with many new features, such as:

Significantly improved matching accuracy.
A more streamlined estimate flow.
Significantly more emission factor metadata.

This document is the changelog & upgrade guide for the GA version. See our API versioning guide for how API versioning works at Climatiq. View the Mapping Agent API reference to get all the details, including request & response bodies..

The GA version of Mapping Agent is available at:


https://api.climatiq.io/mapping-agent/v1/

The existing v1-preview4 version of Mapping Agent is now deprecated, and will be removed in January 2027.

Notable Changes

Matching Improvements

The GA version of Mapping Agent comes with significant matching improvements. For many queries Mapping Agent already performed well, but our new version performs significantly better, particularly on more ambiguous queries, or queries in non-english languages.

This new improved matching is the default, and we recommend trying it out for your workloads.

The increased accuracy does come with an increased latency. If you are in a situation where low latency is important, and you want to optimize for that, rather than the best matching accuracy, you can set the effort parameter to low (down from the default high)

Removal of `translation` flag

The translation flag has been removed. If effort is high and you provide a non-english query, it is translated automatically.

Suggest Returns More Data

Previously the /suggest endpoint returned only a subset of the data available for each emission factor. This has been streamlined, so for each emission factor, /suggest now returns the same fields as the search endpoint.

This means you can now view metadata like id, activity_id, and raw emission factor values, if the license for the given emission factor allows it.

Removal of `/suggest/estimate`

In v1-preview4, /suggest returned a suggestion_id that you could use inside the /suggest/estimate endpoint to perform an estimation with the suggested emission factor.

This is no longer necessary. As /suggest returns activity_id for the suggested emission factors, you can use this activity ID directly in the Basic Estimate endpoint instead.

The suggest/estimate endpoint, and the concept of suggestion_id has been removed.

Data Version Update

The data version in Autopilot v1 has been updated to be ^33. This ensures that the data returned is the most up-to-date, and that we don’t return any emission factors that have been deprecated.

This also means that some filters that previously worked might not work anymore, and that some emission factors will no longer be returned.

Removal of `model` Parameter

Previously we experimented with having multiple underlying machine learning models (or domains), but for a long time there’s only ever been one model, and the model parameter was kept for backwards compatibility.

It has now been removed. The endpoints no longer accepts a model parameter, or returns a model field. The model_version field is still returned.

Include Emission Factors for All Scopes by Default

v1-preview4 defaulted to only returning scope 3 factors for backwards compatibility reasons.

v1 of the Mapping Agent defaults to returning emission factors for all scopes, unless the scope parameter is used to filter in applicable scopes.

Different Handling of non-licensed data

Previously in the /suggest endpoint, we returned the best matches, regardless if you had a license for those emission factors or not. We wanted to showcase the best matches we could get. However, in practice this turned out to be confusing, as the emission factors were then not usable afterwards.

The /suggest endpoint now, by default, only suggests emission factors you actually have a license for. If you want to see the best matches, regardless of whether you have a license, set the availability parameter to "include_unavailable". For each emission factor returned by suggest, the returned availability field will also tell you whether you currently have access to the given emission factor.

For the one-shot estimate endpoint, we would previously also return emission factors that the user did not have access to, but with all the CO2e values set to 0. This behavior has been removed. One-shot estimate now only returns calculations, using emission factors you have access to.

There is no way to opt into using unlicensed data for one-shot-estimate. If you want to see the best matches, regardless of whether you have access, you should use /suggest.

Migration Guide (from v1-preview4)

Migrating should be reasonably straightforward in most cases. We’ll list the changes you’ll need to make across all endpoints, and then per-endpoint changes. As always, the reference documentation will contain all the detailed API requests and responses.

For All Endpoints

Change all urls from https://preview.api.climatiq.io/autopilot/v1-preview4/* to https://api.climatiq.io/mapping-agent/v1/* (note the removal of the preview part in both the domain and the path)
The model parameter no longer exists in any endpoints. You don’t need to send it, and it will not be returned.
By default, emission factors matching all scopes are now included. If you want to replicate the old behavior of only allowing factors for scope 3, you should set the scope filter like this:scope: ["3"]
If you get an error that some of your filters are no longer valid, it is because they no longer exist in the latest data version. We recommend updating them to the newer versions. If you are unsure what to update them to, please reach out to our support team
There is a newly introduced effort parameter for all endpoints, which is set to high by default. This is significantly more accurate than the matching in v1-preview4, but at the cost of higher latency. Evaluate whether you need to set this parameter to low, to achieve latency comparable with v1-preview4.
Stop sending the translation parameter. If effort is set to high (the default), translation happens automatically. If you need to use effort set to low for latency reasons and you have non-english queries, you should do the translation on your side.
View the updated list of notice codes that can be returned, and adapt your code accordingly. All new notices have to do with inflation adjustment, so if you are not using this functionality, you don’t need to make any changes.

Specifically for `/suggest`

Check out the new fields suggest returns, to capture the ones that are important to you like id, activity_id or factor.
suggestion_id no longer exists as a concept, and is no longer returned by the API.
Previously /suggest would return factors that you did not have a license to, so you could see the best matches. While this behavior still exists, you must now opt-in to it via setting the availability: "include_unavailable" parameter. Otherwise /suggest will only return emission factors your current license allows you to use. You can see which emission factors are currently available to you through the new availability field. Read more about this behavior in the API reference

Specifically for `/suggest/estimate`

This endpoint no longer exists. If you previously took suggestion_id from /suggest and used it in this endpoint, we recommend you instead take the activity_id and use it in the Basic Estimate endpoint instead.
Basic Estimate also supports inflation adjustments for money based factors if you need it.
The inflation_adjustment parameter has changed slightly. See the API reference for the new structure if you are supplying this parameter.
The returned calculation_details no longer returns inflation_applied. The applied inflation is returned in a notice instead.

Specifically for `/estimate`

Previously /estimate could return factors that you did not have a license to, so you could see the best matches. These factors would always be returned with a co2e of 0. This functionality no longer exists, and /estimate will only use emission factors you have access to. If you wish to see which emission factors are the best match for your query, regardless of whether you currently have a license, you can use the /suggest endpoint with the availability parameter.
The inflation_adjustment parameter is no longer a boolean, but an optional number. You can then specify the year you want inflation adjustment from - which might be different from the year that you want to filter your emission factors on.
Calculation details no longer returns an inflation_applied number. The inflation applied (if any), is now returned within a notice instead.
Previously /estimate would use factors that you did not have a license to for estimates, so you could see the best matches. This meant that you could see estimates with a co2e of 0 because you did not have access to the emission factor. This behavior has been removed, and /estimate will only use emission factors that are available to you.