API Reference
Autopilot (preview 1)

Autopilot ADD-ONADD-ON

🚫
Newer version available

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

⚠️
Preview Feature

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:

Request parametersShould be sent as a JSON object in the body
    • textrequired string

      The free-form input text, such as an activity name, service or material name.

    • parametersrequired Parameters object

      Calculation parameters. Currently the only unit types that are supported are Weight, Money, Volume and Number

    • domainrequired string

      One of the Domains to be used for the calculation.

    • yearinteger
      Default 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.

    • 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_fallbackboolean
      Default 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 is false

Domains

Domains represent a collection of data and heuristics, defined for specific use cases.

ValueDescriptionDatasetsSources
generalGeneral list of materials and servicesClimatiqAll non-premium sources in the EFDB
general_and_ecoinventGeneral list of materials and services, from both the Climatiq database and ecoinventClimatiq, ecoinventAll sources in general, plus ecoinvent
ecoinventGeneral list of materials and services from ecoinventecoinventecoinvent
exiobaseSpend-based emission factors from EXIOBASEClimatiqEXIOBASE
manufacturingList of materials and services relevant for the manufacturing industry aggregated from various sourcesClimatiqCircular Ecology, OEKOBAUDAT, BEIS, CBAM, EXIOBASE, EPA, GEMIS, Climate Trace
manufacturing_and_ecoinventList of materials and services relevant for the manufacturing industry aggregated from various sources incl. ecoinventClimatiq, ecoinventAll 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.

Response parameters
    • 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_statestring

      State of the review of this calculation. Possible values are: human_review_requested, human_review_in_progress or human_review_finished.


      calculation_details[x].last_human_review_atstring

      Last human review date if any.


      calculation_details[x].confidencestring

      Confidence level of the matching between the input and the emission factor. Possible values are: high, medium and low.


      calculation_details[x].similarity_scorefloat or null

      The 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.92,
"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)"
}
]
}
A finished review with a “low” confidence label

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:

Request parametersShould be sent as a JSON object in the body
    • estimaterequired object

      Object with request submitted to Estimate above.

    • max_suggestionsnumber
      Default 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.

⚠️
Overrides and reviews in suggest endpoint

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:

Response parameters
    • 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].confidencestring

      Confidence level of the matching between the input and the emission factor. Possible values are: high, medium and low.


      calculation_details[x].similarity_scorefloat or null

      The 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": 95.3,
"co2e_unit": "kg",
"co2e_calculation_method": "ar5",
"co2e_calculation_origin": "source",
"emission_factor": {
"name": "Cement",
"activity_id": "building_materials-type_cement",
"id": "c7207a20-7747-42bb-bccc-3dcd6ce16808",
"access_type": "public",
"source": "GEMIS",
"source_dataset": "GEMIS model and database v5.0",
"year": 2015,
"region": "DE",
"category": "Building Materials",
"source_lca_activity": "upstream-use_phase-transport",
"data_quality_flags": []
},
"constituent_gases": {
"co2e_total": 95.3,
"co2e_other": null,
"co2": 93.3,
"ch4": 0.05,
"n2o": 0.002
},
"activity_data": {
"activity_value": 100,
"activity_unit": "kg"
},
"audit_trail": "enabled"
},
"calculation_details": {
"similarity_score": 1,
"confidence": "high"
},
"source_trail": [
{
"data_category": "emission_factor",
"name": "Cement",
"source": "GEMIS",
"source_dataset": "GEMIS model and database v5.0",
"year": "2015",
"region": "DE",
"region_name": "Germany"
}
]
},
{
"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.95,
"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"
}
]
}
]
}

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:

Request parametersShould be sent as a JSON object in the body
    • 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.

Response parameters
    • 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:

Request parametersShould be sent as a JSON object in the body
    • 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.

Response parameters
    • 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."
}