Autopilot ADD-ONADD-ON

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:

Domains

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

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.

Calculation Details

The calculation_details object includes the following attributes.

{
    "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.83,
        "confidence": "high"
    }
}

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:

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:

Calculation Details

The calculation_details object for each suggestion includes the following attributes.

{
    "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"
            }
        },
        {
            "estimate": {
                "co2e": 18.36,
                "co2e_unit": "kg",
                "co2e_calculation_method": "ar4",
                "co2e_calculation_origin": "source",
                "emission_factor": {
                    "name": "Cement screed",
                    "activity_id": "building_materials-type_cement_screed",
                    "id": "38d97210-cdc4-4637-bb55-3e669350252d",
                    "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": 18.36,
                    "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.92,
                "confidence": "high"
            }
        }
    ]
}

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:

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
        }
    },
    "reason": "Result is not specific enough"
}'

Response

The response includes a confirmation message of the request.

{
    "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:

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
        }
    },
    "override_activity_id": "building_materials-type_cement"
}'

Response

The response includes a confirmation message of the request.

{
    "message": "Activity 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."
}