Autopilot ADD-ONADD-ON
You are reading documentation for an older version of this feature. We recommend you view the documentation for the latest version of this feature, which is available here.
This version of the feature will be removed: February 2025
This feature is currently in preview. That means that we believe the feature is good enough to start using, but:
- There might still be bugs or edge cases we haven't covered.
- The documentation and error messages might be less detailed.
- We might need to make further changes in the API surface.
We need the ability to iterate quickly on preview versions, so we offer less guarantees of stability. When we make changes to the preview version, we will release a new version, and you must migrate to this new version within one month. Read more about API versioning at Climatiq here.For this reason, preview endpoints are not available without explicitly opting in. If you would like to opt-in to this preview feature, please contact us.
Autopilot is an AI-powered calculation endpoint designed to automate spend- and activity-based emission estimates. It uses a proprietary natural language processing (NLP) model paired with Climatiq’s scientific expertise to streamline complex emission calculations, making carbon insights accessible to non-experts.
Autopilot significantly reduces the time and manual effort spent identifying the appropriate emission factors and mapping activity data. Capable of ingesting any taxonomy and unstructured data, this feature matches raw text content to the correct emission factors and delivers accurate and compliant emission estimates.
Leveraging a built-in expert review mechanism and machine learning, Autopilot's matching algorithm consistently refines its precision. This is achieved through active feedback and continuous improvement of the underlying NLP model.
Estimate
POST Calculate total estimated emissions produced for a particular activity, in kgCO2e
,
using free-text input. The best matching emission factor will automatically be selected and used
for the calculation. All requests are performed by sending a POST request to the following endpoint.
https://preview.api.climatiq.io/autopilot/v1-preview1/estimate
Request
This endpoint accepts the following parameters:
- textrequired string
The free-form input text, such as an activity name, service or material name.
- parametersrequired Parameters object
- domainrequired string
One of the Domains to be used for the calculation.
- yearintegerDefault value: Latest year available
The year which the activity occurred. Climatiq will attempt to find an emission factor as close to this year as possible, but might not match the year entirely.
Default ValueLatest year available - regionstring
The geographic region where the activity was performed. If this is not provided, Climatiq will pick from emission factors all over the world. If this is provided, Climatiq will only find emission factors matching the supplied region, unless
region_fallback
is set. - region_fallbackbooleanDefault value:
false
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. Default isfalse
Default Valuefalse
Domains
Domains represent a collection of data and heuristics, defined for specific use cases.
Value | Description | Datasets | Sources |
---|---|---|---|
general | General list of materials and services | Climatiq | All non-premium sources in the EFDB |
general_and_ecoinvent | General list of materials and services, from both the Climatiq database and ecoinvent | Climatiq, ecoinvent | All sources in general , plus ecoinvent |
ecoinvent | General list of materials and services from ecoinvent | ecoinvent | ecoinvent |
exiobase | Spend-based emission factors from EXIOBASE | Climatiq | EXIOBASE |
manufacturing | List of materials and services relevant for the manufacturing industry aggregated from various sources | Climatiq | Circular Ecology, OEKOBAUDAT, BEIS, CBAM, EXIOBASE, EPA, GEMIS, Climate Trace |
manufacturing_and_ecoinvent | List of materials and services relevant for the manufacturing industry aggregated from various sources incl. ecoinvent | Climatiq, ecoinvent | All sources in manufacturing , plus ecoinvent |
Dry-runs
If you attempt to estimate using domain
with a dataset that your API key does not have access to, the estimate will still work,
but the CO2e values will not be provided. This is so you can evaluate how good matches would be using different domains and datasets,
before purchasing commercial access to the data.
curl --request POST \ --url https://preview.api.climatiq.io/autopilot/v1-preview1/estimate \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "domain": "general", "text": "Steel", "parameters": { "money": 100, "money_unit": "usd" }}'
Response
The response includes the CO2e estimate and details about the calculation.
- estimateEstimation
The estimation performed returning the total CO2e value, constituent gases and more.
- calculation_detailsobject
Details about the calculation, including review state and confidence level.
calculation_details[x].review_statestringState of the review of this calculation. Possible values are:
human_review_requested
,human_review_in_progress
orhuman_review_finished
.calculation_details[x].last_human_review_atstringLast human review date if any.
calculation_details[x].confidencestringConfidence level of the matching between the input and the emission factor. Possible values are:
high
,medium
andlow
.calculation_details[x].similarity_scorefloat or nullThe numeric similarity score between the input and the emission factor. The number is between 0 and 1, and a higher score indicates a better match. If the emission factor was selected as the basis of a human review, the similarity score will be
null
. - source_trailarray of Source Data Point
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about Source Trail.
{ "estimate": { "co2e": 47, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Cast iron and steel", "activity_id": "metals-type_cast_iron_steel", "id": "15e75a68-b485-494b-8cbc-398d417207a7", "access_type": "public", "source": "EPA", "source_dataset": "Supply Chain Factors Dataset (commodities)", "year": 2018, "region": "US", "category": "Metals", "source_lca_activity": "cradle_to_shelf", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": null, "co2e_other": 0.7, "co2": 41.3, "ch4": 0.2, "n2o": 0 }, "activity_data": { "activity_value": 100, "activity_unit": "usd" }, "audit_trail": "enabled" }, "calculation_details": { "review_state": "unreviewed", "last_human_review_at": null, "similarity_score": 0.91, "confidence": "high" }, "source_trail": [ { "data_category": "emission_factor", "name": "Cast iron and steel", "source": "EPA", "source_dataset": "Supply Chain Factors Dataset (commodities)", "year": "2018", "region": "US", "region_name": "United States of America (the)" } ]}
Note that the confidence label might still be low even after a human review has been finished, e.g. if the string can't be matched to a more relevant emission factor because there is not enough information to match to, or if no well-matched emission factors could be found, but less relevant factors were available. Supplementing more information in the input string and initiating another human review could help us find a higher quality match.
Handling Errors
If the calculation has been through the review process, an error could be returned if your input is not of sufficient quality. In such cases, revise your input string and submit it as a new estimate request.
{ "error": "bad_request", "error_code": "invalid_input", "message": "No emission factors could be found based on the input text. A human review has been finished, and your input is not of sufficient quality to match it to any data. Please revise your input string.",
}
It could also result in an error if no emission factors could be found during a review. Please contact us if you would like to submit a data request to add relevant emission factors into our database.
{ "error": "bad_request", "error_code": "no_emission_factors_found", "message": "No emission factors could be found based on the input text. A human review has been finished, but we did not have the correct data to match your input."}
Suggest
POST Return a number of autopilot suggested estimates for a particular calculation. You can adjust the number of suggestions to return. Suggestions are ordered by the most likely match first.
https://preview.api.climatiq.io/autopilot/v1-preview1/suggest
Request
This endpoint accepts the following parameters:
- estimaterequired object
Object with request submitted to Estimate above.
- max_suggestionsnumberDefault value: 10
The maximum number of suggestions to receive. Autopilot will return as many suitable suggestions as it can find, up to the max number requested, or at most 20 suggestions.
Default Value10
The suggest endpoint does not take into account overrides or human reviews. It offers a snapshot of outcomes generated by our matching algorithm. These results may vary over time as a result of enhancements to the algorithm. If you need your queries to respect overrides or human reviews, please use the Autopilot estimate endpoint.
Dry-runs
Similar to the estimate endpoint's dry-run feature, using a domain with a dataset that your API key does not have access to allows you to see details of the estimation without the CO2e value. This enables you to evaluate the accuracy of the matches provided by autopilot.
curl --request POST \ --url https://preview.api.climatiq.io/autopilot/v1-preview1/suggest \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "estimate": { "domain": "general", "text": "Cement", "parameters": { "weight": 100, "weight_unit": "kg" } }, "max_suggestions": 2}'
Response
The response includes a list of objects, each containing the following:
- estimateEstimation
The estimation performed returning the total CO2e value, constituent gases and more.
- calculation_detailsobject
Details about the calculation, including review state and confidence level.
calculation_details[x].confidencestringConfidence level of the matching between the input and the emission factor. Possible values are:
high
,medium
andlow
.calculation_details[x].similarity_scorefloat or nullThe numeric similarity score between the input and the emission factor. The number is between 0 and 1, and a higher score indicates a better match. If the emission factor was selected as the basis of a human review, the similarity score will be
null
. - source_trailarray of Source Data Point
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about Source Trail.
{ "results": [ { "estimate": { "co2e": 79.52, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Cement (CEM II 42.5)", "activity_id": "building_materials-type_cement_cem_ii_42.5", "id": "d022f8c4-d039-4349-a05a-21c181c68471", "access_type": "public", "source": "OEKOBAUDAT", "source_dataset": "OEKOBAUDAT 2023-I", "year": 2018, "region": "DE", "category": "Building Materials", "source_lca_activity": "cradle_to_gate", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 79.52, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 100, "activity_unit": "kg" }, "audit_trail": "enabled" }, "calculation_details": { "similarity_score": 0.93, "confidence": "high" }, "source_trail": [ { "data_category": "emission_factor", "name": "Cement (CEM II 42.5)", "source": "OEKOBAUDAT", "source_dataset": "OEKOBAUDAT 2023-I", "year": "2018", "region": "DE", "region_name": "Germany" } ] }, { "estimate": { "co2e": 211, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Aluminous cement", "activity_id": "building_materials-type_aluminous_cement", "id": "78ea9f9b-0e18-4f28-b660-b98a03979e90", "access_type": "public", "source": "CBAM", "source_dataset": "Emission intensities at country level", "year": 2023, "region": "BA", "category": "Building Materials", "source_lca_activity": "total", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 211, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 100, "activity_unit": "kg" }, "audit_trail": "enabled" }, "calculation_details": { "similarity_score": 0.93, "confidence": "high" }, "source_trail": [ { "data_category": "emission_factor", "name": "Aluminous cement", "source": "CBAM", "source_dataset": "Emission intensities at country level", "year": "2023", "region": "BA", "region_name": "Bosnia and Herzegovina" } ] } ]}
Request Review
POST Request a review of a particular calculation.
https://preview.api.climatiq.io/autopilot/v1-preview1/request-review
Request
This endpoint accepts the following parameters:
- estimaterequired object
Object with request submitted to Estimate above.
- reasonstring
Optional reason or explanation for the review request.
curl --request POST \ --url https://preview.api.climatiq.io/autopilot/v1-preview1/request-review \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "estimate": { "domain": "general", "text": "Cement", "parameters": { "money": 100, "money_unit": "usd" } }, "reason": "Result is not specific enough"}'
Response
The response includes a confirmation message of the request.
- messagestring
Confirmation message.
{ "message": "request registered"}
Override
POST Override the automatically assigned activity for a calculation by providing an activity ID. All future autopilot calls to the autopilot estimate endpoint for this calculation will be performed with the selected activity.
https://preview.api.climatiq.io/autopilot/v1-preview1/override
Request
This endpoint accepts the following parameters:
- estimaterequired object
Object with request submitted to Estimate above.
- override_activity_idrequired string
A valid activity ID for emission estimation.
curl --request POST \ --url https://preview.api.climatiq.io/autopilot/v1-preview1/override \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "estimate": { "domain": "general", "text": "Cement", "parameters": { "money": 100, "money_unit": "usd" } }, "override_activity_id": "building_materials-type_cement"}'
Response
The response includes a confirmation message of the request.
- messagestring
Confirmation message.
{ "message": "override registered"}
Providing a valid activity ID
The override request can be rejected if the provided activity ID is invalid, or no emission factors associated with this activity ID is suitable for this query.
{ "error": "bad_request", "error_code": "no_emission_factors_found", "message": "The activity ID override you specified would not work with the rest of your query. The error you would get when trying it is: No emission factors could be found using the current query."}