Autopilot Integration Guide

⚠️

This integration is based on version v1-preview3 of Autopilot (the latest version). Please consider upgrading to this version if you are using an earlier version of the feature.

Use this guide to build the outline of your integration with Autopilot API. Autopilot helps you to map your data, such as purchases, component lists, and other data points to the correct emission factors within scope 3.1 of the GHG Protocol (Purchased Goods & Services).

By the end of this guide, you'll know how to:

Receive emission factor suggestions for your data from Autopilot Suggest
Select the most suitable emission factor for your calculation
Calculate carbon emissions estimates using Autopilot Estimate

Before you begin

You must first obtain a Climatiq API key from the Climatiq Dashboard (opens in a new tab). You can read how to do this in this guide.

How Autopilot integrates into your application

In this guide, you'll learn how to integrate Autopilot's automated emission calculations into your application and map customer data to emission estimations. For example, suppose you are a SaaS platform providing emissions estimates based on your customer's procurement data. You can use Autopilot to automatically match each item to an emission factor and display a calculated CO2e estimate.

This consists of the following steps:

Sending your data to Autopilot Suggest and receiving matching emission factors
Selecting the most suitable emission factor from the suggestion list
Sending an Autopilot Estimate request using your selected emission factor to get a CO2e estimate

Below, you can see a diagram that gives you a high level overview of these steps.

Input Data

For the integration to work, you will need to have:

Text-based input data, i.e. invoice line items, component data, or similar
- The input data should be human-readable (see examples in the table below)
Units and respective quantities for each line item, i.e. 1 kg
- Units should be either Weight, Volume, Number, or Money. Read about Climatiq units here.

An example of good input data for Autopilot is specified below:

Input	Tips & tricks
hardened rubber 9572 green	This input is clear, but in order to get a more precise match, try supplying more data about the rubber and what it is used for.
Disodium carbonate	Clear input without any ambiguity.
copper pipe 10mm	Clear input without any ambiguity, however, it’s beneficial to leave out information such as size and proprietary numbers from the input.
plastic; shielding film; building construction material;	Clear input. Great example of how category and overall input descriptions can give Autopilot more context.

Get options from Autopilot Suggest

Autopilot Suggest gives you list of emission factor suggestions for the text input you provide. You can also narrow down the results using multiple different filters.

To get a calculated estimation of carbon intensity, you will need to select one of Autopilot's emission factor suggestions. You can either provide these as options to your users or select it automatically based on the similarity score that we provide.

When you have selected the emission factor with the best fit, you will need to save its suggestion_id for any subsequent calls to the Autopilot Estimate endpoint.

Below, you can see a possible interaction model for your data and Climatiq's Suggest API.

Choosing a domain

Domains allow Autopilot to fine-tune matching results and take sector specific patterns into account. Domains also filter out a number of sources by default, which allows Autopilot to narrow down the pool of options and, in some cases, increase matching quality.

In other words, Domains can improve matching quality in two ways: by changing the underlying model used and the underlying set of sources used.

You can view currently available domains in the Autopilot API Reference. By default, we recommend using the general domain if you have data that is diverse or is not sector specific.

You can use as many domains as you like, across multiple calls. Please note that some domains can be limited access only and will be marked as such in documentation. If you would like to have access, please contact us (opens in a new tab).

You should use specific Autopilot domains when:

Your data mostly consists of items used in respective industry operations or processes
You have items that are very specific to a certain industry, such as rare materials
You have tried the general domain and had found that results are not fully aligned with the specifics of your data

Using filters

Filters allow you to refine emission factor suggestions provided by Autopilot by providing additional context in the request body. These filters help narrow results to match the details of your emission-generating activity. You can check currently available filters in the Autopilot API Reference.

As an example, filters can help you get an emission factor with a region, a relevant year, and lifecycle activity, as well as from specific sources. If you want to search for emission factors from EXIOBASE, include EXIOBASE in the source field of your request.

Selecting a filter option

Some filter options are restricted by the domain that you are using with Autopilot. For example, the manufacturing domain contains a subset of sources from the Climatiq database. This means that you can only include or exclude sources from this list of sources. See the Domains section for a list of sources available in each domain.

Similarly, only a subset of lifecycle activities are available in each domain. If you have indicated a LCA activity that is not available for the domain you have specified, the API will return a list of available source_lca_activity to you for this particular domain. For a full list of source_lca_activity, see this guide on using LCA activities with Climatiq (opens in a new tab).

Note that applying multiple filters at the same time can sometimes lead to little to no results. When this happens, consider relaxing some of the filters you have applied to broaden the search range, or enable the region_fallback flag.

You should adjust your filters when:

You need data for a specific LCA stage, from a specific source, or for a specific region
You got no results back on the first try, so should query Autopilot with relaxed filters

Using region fallback

The region filter is useful for targeting emission factors specific to a geographical area. However, some regions may lack sufficient data, leading to limited results.

You can enable the region_fallback flag to receive emission factors that are less specific than the region you have specified. Set this to true if you're willing to accept a less specific geographical region than the one you've specified. Climatiq will then intelligently attempt to select a different region if it does not find any emission factors with the initial region.

You should use region fallback when:

Your item doesn't have a good match in the region you have initially specified
You received no results when specifying a particular region

Using multiple units

Autopilot Suggest allows you to specify one or more units when performing emission factor matching. This allows you to expand your emission factor search in case you have data in multiple units, e.g. you have both the weight and price of the item you are trying to match to an emission factor.

For example, the most suitable emission factor for your data might be associated with the Money unit (e.g., emissions per dollar of goods). However, if you only specify Weight as the unit, the best match could be overlooked. This is because emission factors must use a unit of measurement to calculate emissions, e.g. a Money emission factor will always measure emissions per dollar of goods.

If you have data in more than one unit type available, we typically recommend including multiple units in your request and expanding the set of possible matches to increase the probability of finding a perfect emission factor.

Climatiq emission factors for activity-based estimations typically use Weight as the unit of input, but we also have an extensive library of Money, Volume, and other emission factors.

You should specify multiple units in your Autopilot Suggest request when:

You have data covering 2+ units for one line item, e.g. both Weight and Money
You are looking to get the best possible matches across all units and don’t need to keep the unit of your calculation outputs consistent

Select emission factor from Suggest results

After receiving Autopilot Suggest results, you need to select the best fitting emission factor to send to the Autopilot Estimate endpoint and perform a CO2e estimate.

For that, you need to perform two steps:

Select the emission factor either manually or automatically in your application
Send the suggestion_id of the emission factor to the Autopilot Estimate endpoint

Generally, we recommend the following workflow to select the emission factor:

Using `suggestion_id`

Every emission factor Autopilot returns is associated with a suggestion_id identifier. Once you have reviewed and selected the most suitable factor from the list of suggestions, you can use this ID to make a subsequent call to the Estimate endpoint with the same factor.

Note that suggestion_ids do not persist across endpoint versions. An Autopilot suggestion generated in v1-preview2 cannot be used for estimating emissions in v1-preview3.

Using similarity scores

Similarity score is returned as a separate field in the API. Climatiq returns suggestions ordered from most likely to least likely based on our proprietary scoring model.

Similarity scores help you decide if you should use the emission factor or not. They signal if we think that emission factor is a good match for your item and can be displayed to users to guide their decisions.

If you don’t want users to select emission factors themselves, you can automatically pick the top-rated factor from the response based on similarity scores.

We recommend to only automatically select the emission factor when the similarity score is equal to or more than 0.85. This way, you ensure that most of the mapped results make sense and that you validate any results the model is unsure about.

You should use similarity score when:

You want to automatically select the emission factors for further Estimate calls
You want to give users of your application guidelines on whether this data seems like a likely match
You want to speed up the emission factor matching process by having an easy metric to refer to when doing emission factor match verification

Calculate emissions using Estimate

After you have selected an emission factor and have stored the suggestion_id of the factor from the Suggest call, the next step is calculating the emissions.

To calculate the emissions of the selected activity, you need to send a request containing suggestion_id and a parameter object matching the factor's unit_type, along with its quantity to the Estimate endpoint. As a response, you will see the emissions estimate calculation along with metadata about the emission factor.

Reusing emission factor matches

We recommend storing results from Suggest and Estimate. This is because as data versions get updated, different emission factors might be returned. Results may also change as we make updates and enhancements to the underlying Autopilot model to improve precision and accuracy. You may receive better emission factor matches in Suggest, and these may not match the emission factors you received in a previous request.

Storing emission factor calculations

If it is important to you to keep a trail of your calculations, we recommend saving both the emission calculation result and the details of calculation (e.g. emission factor name, source, year, and others) in your application.

Google Sheets Extension Get an API Key