Autopilot (preview 2) 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.

Suggest

POST Return a number of suggested emission factors 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-preview2/suggest

Request

This endpoint accepts the following parameters:

curl --request POST \
  --url https://preview.api.climatiq.io/autopilot/v1-preview2/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 emission factors and details about its relevance:

{
    "results": [
        {
            "suggestion_id": "mj2ws3denfxgox3nmf2gk4tjmfwhgllupfygkx3dmvwwk3tu-mq3tszbumjtdczjrmfrdinbwgi4tsmrsgaydambqgaydambqgayq",
            "emission_factor": {
                "sector": "Materials and Manufacturing",
                "category": "Building Materials",
                "name": "Cement",
                "unit_type": "Weight",
                "unit": "kg/kg",
                "source": "GEMIS",
                "source_dataset": "GEMIS model and database v5.0",
                "year": 2015,
                "year_released": 2021,
                "region": "DE",
                "region_name": "Germany",
                "description": "Emission intensity of production of Portland cement. This emission factor reflects manufacturing effort for the provision of selected building materials in Germany in 2015 (average data). Where necessary foreign shares (imports) are included. Total life cycle incl. transport + material input excl. disposal. Reference point is product provision (without use). Retrieved from GEMIS v5.0.",
                "source_link": "https://iinas.org/downloads/gemis-downloads/",
                "source_lca_activity": "upstream-use_phase-transport",
                "data_quality_flags": [],
                "access_type": "public"
            },
            "suggestion_details": {
                "similarity_score": 1,
                "confidence": "high"
            }
        },
        {
            "suggestion_id": "mj2ws3denfxgox3nmf2gk4tjmfwhgllupfygkx3dmvwwk3tul5rwk3k7nfuv6nbsfy2q-mq3tszbumjtdczjrmfrdinbwgi4tsmrsgaydambqgaydambqgayq",
            "emission_factor": {
                "sector": "Materials and Manufacturing",
                "category": "Building Materials",
                "name": "Cement (CEM II 42.5)",
                "unit_type": "Weight",
                "unit": "kg/kg",
                "source": "OEKOBAUDAT",
                "source_dataset": "OEKOBAUDAT 2023-I",
                "year": 2018,
                "year_released": 2023,
                "region": "DE",
                "region_name": "Germany",
                "description": "Emission intensity of cement (cem ii 42.5). The lifecycle assessment for modules A1-A3 includes: the extraction and processing of raw materials (A1) their transportation to the manufacturer (A2) and the actual manufacturing of the product (A3). Retrieved from the Oekobaudat database v20.19.120.",
                "source_link": "https://www.oekobaudat.de/en/service/downloads.html",
                "source_lca_activity": "cradle_to_gate",
                "data_quality_flags": [],
                "access_type": "public"
            },
            "suggestion_details": {
                "similarity_score": 0.95,
                "confidence": "high"
            }
        }
    ]
}

Estimate

POST Calculate total estimated emissions produced for an autopilot matched activity, in kgCO2e. All requests are performed by sending a POST request to the following endpoint.

Estimations can be performed with a suggested activity from the Suggest endpoint, or by using free-text input, which will automatically calculate emissions with the best emission factor match.

https://preview.api.climatiq.io/autopilot/v1-preview2/estimate

Calculation using suggestion

Receive an estimation for a suggested emission factor match. When you receive a list of suggested emission factors using the Suggest endpoint, you can request for a calculation using the following parameters.

You may specify a different year and region from the suggest query - an estimation will be returned if an emission factor can be found with these parameters using an identical activity ID.

Request

curl --request POST \
  --url https://preview.api.climatiq.io/autopilot/v1-preview2/estimate \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
  --data '{
	"suggestion_id": "mj2ws3denfxgox3nmf2gk4tjmfwhgllupfygkx3dmvwwk3tu-gaydambqgaydambqgaydambqgaydambqgaydambqgaydambqgayq",
	"parameters": {
		"weight": 100,
        "weight_unit": "kg"
	}
}'

Response

The response includes the CO2e estimate and details about the calculation.

{
    "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"
    },
    "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"
        }
    ]
}

Calculation using free-text input

Request

Receive an estimation for the best emission factor match using the following parameters.

curl --request POST \
  --url https://preview.api.climatiq.io/autopilot/v1-preview2/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.

{
    "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)"
        }
    ]
}

Dry-runs

If you attempt to estimate with free-text input 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.

Handling Errors

If the calculation using free-text input 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."
}

Request Review

POST Request a review of a particular calculation made with free-text input. Climatiq's in-house experts will conduct a evaluation of the emission factor match. Once reviewed, any subsequent calculation requests using free-text input with identical parameters will automatically match the expert-reviewed emission factor. This process ensures that emission factor matches are fine-tuned based on Climatiq's carbon expertise, improving the accuracy of future calculations.

https://preview.api.climatiq.io/autopilot/v1-preview2/request-review

Request

This endpoint accepts the following parameters:

curl --request POST \
  --url https://preview.api.climatiq.io/autopilot/v1-preview2/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.

{
    "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 using free-text input for this calculation will be performed with the selected activity.

https://preview.api.climatiq.io/autopilot/v1-preview2/override

Request

This endpoint accepts the following parameters:

curl --request POST \
  --url https://preview.api.climatiq.io/autopilot/v1-preview2/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.

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

Domains

Domains represent a collection of data and heuristics, defined for specific use cases, and restricts the datasets used for matching emission factors.