Skip to Content
API ReferenceMapping AgentMapping Agent v1

Mapping Agent Endpoint version: V1V1 ADD-ONADD-ON

For an overview of how to integrate Mapping Agent into your application, we have added an Mapping Agent integration guide to guide you through the process. To see the changes since v1-preview4, see our changelog.

The Mapping Agent (formerly Autopilot) is an AI-powered calculation endpoint designed to automate spend- and activity-based emission estimates across scope 1, 2, and 3 emissions. It uses a mix of large language models (LLMs), and 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.

The Mapping Agent 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 and contextual information to find the correct emission factors and delivers accurate and compliant emission estimates.

The Mapping Agent’s matching algorithm consistently refines its precision. This is achieved through active feedback and continuous improvement of the underlying models.

Premium sources and datasets ADD-ONADD-ON

Some premium datasets, like ecoinvent and the EXIOBASE 3.10 and later datasets, require a license on top of the core Climatiq access.

If you are debating whether to buy a license for premium data, or just want to see the best match for any given query, regardless of whether you have access, you can set the availability parameter to "include_unlicensed" in the Suggest Endpoint. If you do that, all emission factors are considered. You can tell whether you have access to an emission factor with your current license, by looking at the availability field returned under each.

For data that is unavailable to you, the factor values will be hidden, and you won’t be able to use them in Basic Estimate. They are only provided so you can evaluate what datasets have good matches for your query.

Private emission factors ADD-ONADD-ON

While the Mapping Agent has access to a comprehensive range of emission factors, sometimes you may want to include custom emission factors when performing emission factor matches. You may access your private emission factors as part of the Mapping Agent, by first uploading them through the Private Factors API, or through the Dashboard. To enable this add-on feature, please reach out to us via the contact form .

When private emission factors are enabled, the Mapping Agent searches across both your private emission factors and Climatiq’s database. You can use the filter fields (unit_type, year, region, source, exclude_source, and source_lca_activity) to refine results based on the attributes you defined when uploading your private factors. Note that the scope and source_dataset filters are not currently available for private emission factors. To restrict the Mapping Agent to search only your private emission factors, specify "access_type": "private".

Suggest

POST Return a number of suggested emission factors. The Suggest endpoint finds emission factors that you can use to calculate emissions with via the Basic Estimate endpoint. You can adjust the number of suggestions to return, or filter the results by source, year, region, unit, or lifecycle activity. Suggestions are ranked, with the most relevant result presented first.

https://api.climatiq.io/mapping-agent/v1/suggest

Request

This endpoint accepts the following parameters:

Request headersRequired HTTP headers for this request
    • Authorizationrequired string
      Bearer token containing your Climatiq API key. Example: Authorization: Bearer CLIMATIQ_API_KEY
      Don't have an API key? Get your API key here.
Request parametersShould be sent as a JSON object in the body
    • suggestobject

      Details of the emission-generating activity.

      suggest.textrequired string

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

      suggest.sectorarray of string

      Filters emission factors by the sector they belong to.

      suggest.categoryarray of string

      Filters emission factors by the category they belong to.

      suggest.unit_typearray of unit_types
      Default value: All unit_type

      The unit types of the activity. All unit types are supported.

      suggest.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.

      suggest.regionstring

      A region code describing 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.

      suggest.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. If a region fallback is used, the API will return a Notice.

      suggest.sourcearray of strings
      Default value: All sources

      Filters emission factors by data source. Contains the sources you want to include in your search. You can use either the source or exclude_source parameter, but not both simultaneously. If you have enabled the Private Factors inside Mapping Agent, you can also filter by the source of your private factors.

      suggest.source_datasetarray of strings
      Default value: All source datasets

      Filters emission factors by source_dataset.

      suggest.exclude_sourcearray of strings

      Filters emission factors by data source. Contains the sources you want to exclude in your search. You can use either the source or exclude_source parameter, but not both simultaneously. If you have enabled the Private Factors inside Mapping Agent, you can also filter by the source of your private factors.

      suggest.source_lca_activityarray of strings
      Default value: All source_lca_activity

      Filters emission factors by source_lca_activity. If you have enabled the Private Factors inside Mapping Agent, you can also filter by the source_lca_activity of your private factors.

      suggest.scopearray of strings
      Default value: All scope categories

      Filters by scope, such as 1, 2, 3.1, 3.2, etc. Scope 3 categories can be explicitly stated (such as 3.1) or all Scope 3 categories can be selected by specifying 3.

      suggest.access_typearray of strings
      Default value: All access_type

      Filters by the access type of the emission factors. Allowed values are public, private and premium

      suggest.availability"available_only" or "include_unavailable"
      Default value: "available_only"

      If this is set to available_only, you will only see emission factors that you have access to with your current plan. If set to include_unavailable you will see the best matches, regardless of whether you have access to that given factor. For more details see the section on premium sources and datasets

      suggest.effort"high" or "low"
      Default value: high

      The effort used to match your result to emission factors. The default, high will give significantly better matches but spend more time. We recommend you use high unless you have lower latency requirements.

    • max_suggestionsnumber
      Default value: 10

      The maximum number of suggestions to receive. The Mapping Agent will return as many suitable suggestions as it can find, up to the max number requested, or at most 20 suggestions.

curl --request POST \
  --url https://api.climatiq.io/mapping-agent/v1/suggest \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
  --data '{
    "suggest": {
        "text": "Cement"
    },
    "max_suggestions": 2
}'

Response

The response includes a list of emission factors and details about its relevance:

Response parameters
    • resultsarray

      A list of emission factors for this emission-generating activity.

      results[x].emission_factorSearch Result object

      The suggested emission factor.

      results[x].suggestion_detailsobject

      Details about the suggested emission factor.

      results[x].suggestion_details.labelstring

      Recommendation for a human review of this match between the input and the emission factor. Possible values are: accept and review.

      results[x].suggestion_details.availabilitystring

      If this emission factor is available to use e.g. in Basic Estimate given your current license. This will always be "available" unless you have explicitly set availability to include_unavailable. Possible values are: available and requires_additional_license.

      results[x].noticesarray of Notices

      Any notices relevant to this suggestion

    • model_versionstring

      The version of the Mapping Agent model used to generate this match. Climatiq continuously releases updated models with improvements. This field allows you to identify the model version used and prioritize results from newer versions.

    • data_versionstring

      The data version of the emission factor database used for this estimation. Climatiq continuously updates our database of emission factors. This field allows you to track which data version was applied and prioritize results from newer data versions.

{
    "results": [
        {
            "emission_factor": {
                "id": "9e177562-7665-4a62-85a5-ba42a66d7acc",
                "activity_id": "building_materials-type_cement",
                "name": "Cement",
                "sector": "Materials and Manufacturing",
                "category": "Building Materials",
                "source": "Bafa",
                "source_dataset": "Informationsblatt CO2-Faktoren v3.3",
                "source_link": "https://www.bafa.de/SharedDocs/Downloads/DE/Energie/eew_infoblatt_co2_faktoren_2025.html",
                "source_lca_activity": "cradle_to_gate",
                "year": 2025,
                "year_released": 2025,
                "region": "DE",
                "region_name": "Germany",
                "unit_type": "Weight",
                "unit": "kg/kg",
                "supported_calculation_methods": [
                    "ar4"
                ],
                "factor": 0.77,
                "factor_calculation_method": "ar4",
                "factor_calculation_origin": "source",
                "constituent_gases": {
                    "co2e_total": 0.77,
                    "co2e_other": null,
                    "co2": null,
                    "ch4": null,
                    "n2o": null
                },
                "additional_indicators": {},
                "data_version": {
                    "status": "up_to_date"
                },
                "data_version_information": {
                    "status": "up_to_date"
                },
                "scopes": [
                    "3.1",
                    "3.2"
                ],
                "uncertainty": null,
                "description": "Emission intensity of cement. Retrieved from the file Informationsblatt CO2-Faktoren v3.3 in the source URL. Data quality flag: Methodology - The source does not specify the IPCC AR version of GWPs used to calculate CO2e.",
                "data_quality_flags": [
                    "notable_methodological_variance"
                ],
                "access_type": "public"
            },
            "suggestion_details": {
                "label": "accept",
                "availability": "available"
            },
            "notices": []
        },
        {
            "emission_factor": {
                "id": "5b669229-c575-8310-941f-9948a37fc35e",
                "activity_id": "building_materials-type_cement_production",
                "name": "Cement production",
                "sector": "Materials and Manufacturing",
                "category": "Building Materials",
                "source": "UNFCCC / Turkish Statistical Institute",
                "source_dataset": "2025 Common Reporting Table (CRT)",
                "source_link": "https://unfccc.int/documents/646495",
                "source_lca_activity": "unknown",
                "year": 2023,
                "year_released": 2025,
                "region": "TR",
                "region_name": "Türkiye",
                "unit_type": "Weight",
                "unit": "kg/kg",
                "supported_calculation_methods": [
                    "ar4",
                    "ar5",
                    "ar6"
                ],
                "factor": 0.54784663745,
                "factor_calculation_method": "ar6",
                "factor_calculation_origin": "climatiq",
                "constituent_gases": {
                    "co2e_total": null,
                    "co2e_other": null,
                    "co2": 0.54784663745,
                    "ch4": 0,
                    "n2o": 0
                },
                "additional_indicators": {},
                "data_version": {
                    "status": "up_to_date"
                },
                "data_version_information": {
                    "status": "up_to_date"
                },
                "scopes": [
                    "3.1",
                    "3.2"
                ],
                "uncertainty": null,
                "description": "Emission intensity of industrial processes and product use - CO2 only. Retrieved from sheet: 'Table2(I).A-H' of the 2023 Excel file within the Common Reporting Tables 2025 published by UNFCCC and provided by the Turkish Statistical Institute at the source URL.",
                "data_quality_flags": [],
                "access_type": "public"
            },
            "suggestion_details": {
                "label": "accept",
                "availability": "available"
            },
            "notices": []
        }
    ],
    "model_version": "36",
    "data_version": "33"
}

Errors

When the Mapping Agent is unable to find any emission factor suggestions, it will return the following error. Consider relaxing your filters if you specified any in your request.

{
    "error": "bad_request",
    "error_code": "no_emission_factors_found",
    "message": "No emission factors could be found using the current query."
}

One-shot Estimate

POST Calculate total estimated emissions produced for a Mapping Agent matched activity, in kgCO2e.

Estimations can be performed by using free-text input. It will automatically perform an emission calculation with the best match, using the best matched emission factor, i.e. the top one that would have been suggested by the Suggest endpoint.

https://api.climatiq.io/mapping-agent/v1/estimate

Inflation Adjustments

When using spend-based emission factors for carbon estimation, you can enable automatic adjustments for changes in inflation.

If your expenditure occurred in a different year than the emission factor’s year, your expenditure amount has to be adjusted to match that emission factor’s year. Inflation adjustments are calculated using country-specific inflation data, using rates provided by the World Bank . To enable this feature, set the apply_inflation_adjustment parameter to the year in which you spent the money.

Inflation adjustment methodology

The compound inflation rate, represented as the CIR (Compound Inflation Rate), reflects the cumulative inflation rates over multiple years. To calculate the inflation-adjusted spend amount, the spend should be divided by the CIR for the year following the emission factor’s year (e.g., if the spend occurred in 2021 and the factor is from 2019) and then multiplied by the CIR for the year preceding the emission factor’s year (e.g., if the spend occurred in 2017 and the factor is from 2019).

Request

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

Request headersRequired HTTP headers for this request
    • Authorizationrequired string
      Bearer token containing your Climatiq API key. Example: Authorization: Bearer CLIMATIQ_API_KEY
      Don't have an API key? Get your API key here.
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. All unit types are supported.

    • sectorarray of string

      Filters emission factors by the sector they belong to.

    • categoryarray of string

      Filters emission factors by the category they belong to.

    • 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

      A region code describing 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. If a region fallback is used, the API will return a Notice.

    • sourcearray of strings
      Default value: All sources

      Filters emission factors by data source. Contains the sources you want to include in your search. You can use either the source or exclude_source parameter, but not both simultaneously. If you have enabled the Private Factors inside Mapping Agent, you can also filter by the source of your private factors.

    • source_datasetarray of strings
      Default value: All source datasets

      Filters emission factors by source_dataset.

    • exclude_sourcearray of strings

      Filters emission factors by data source. Contains the sources you want to exclude in your search. You can use either the source or exclude_source parameter, but not both simultaneously. If you have enabled the Private Factors inside Mapping Agent, you can also filter by the source of your private factors.

    • source_lca_activityarray of strings
      Default value: All source_lca_activity

      Filters emission factors by source_lca_activity. If you have enabled the Private Factors inside Mapping Agent, you can also filter by the source_lca_activity of your private factors.

    • scopearray of strings
      Default value: All scope categories

      Filters by scope, such as 1, 2, 3.1, 3.2, etc. Scope 3 categories can be explicitly stated (such as 3.1) or all Scope 3 categories can be selected by specifying 3.

    • access_typearray of strings
      Default value: All access_type

      Filters by the access type of the emission factors. Allowed values are public, private and premium

    • apply_inflation_adjustmentinteger

      The year in which the money was spent. When set on a money-based estimate, the result is adjusted for inflation between this year and the emission factor’s year. See Inflation adjustment.

    • effort"high" or "low"
      Default value: high

      The effort used to match your result to emission factors. The default, high will give significantly better matches but spend more time. We recommend you use high unless you have lower latency requirements.

curl --request POST \
  --url https://api.climatiq.io/mapping-agent/v1/estimate \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
  --data '{
	"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, such as recommendation for a human review.

      calculation_details.labelstring

      Recommendation for a human review of this match between the input and the emission factor. Possible values are: accept and review.

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

    • noticesarray of Notices

      Any notices related to the calculation.

    • model_versionstring

      The version of the Mapping Agent model used to generate this match. Climatiq continuously releases updated models with improvements. This field allows you to identify the model version used and prioritize results from newer versions.

    • data_versionstring

      The data version of the emission factor database used for this estimation. Climatiq continuously updates our database of emission factors. This field allows you to track which data version was applied and prioritize results from newer data versions.

{
    "estimate": {
        "co2e": 69.148512,
        "co2e_unit": "kg",
        "co2e_calculation_method": "ar5",
        "co2e_calculation_origin": "source",
        "emission_factor": {
            "name": "Basic iron and steel",
            "activity_id": "metals-type_basic_iron_and_steel",
            "id": "723f5f50-5765-4a13-9689-dfee93b4a4df",
            "access_type": "public",
            "source": "Climatiq",
            "source_dataset": "Climatiq UK spend-based",
            "year": 2024,
            "region": "GB",
            "category": "Metals",
            "source_lca_activity": "unknown",
            "data_quality_flags": []
        },
        "constituent_gases": {
            "co2e_total": 69.148512,
            "co2e_other": 8.17608,
            "co2": 60.972432,
            "ch4": null,
            "n2o": null
        },
        "additional_indicators": {},
        "activity_data": {
            "activity_value": 78.24,
            "activity_unit": "gbp"
        },
        "audit_trail": "enabled"
    },
    "calculation_details": {
        "label": "accept"
    },
    "source_trail": [
        {
            "data_category": "emission_factor",
            "name": "Basic iron and steel",
            "source": "Climatiq",
            "source_dataset": "Climatiq UK spend-based",
            "year": "2024",
            "region": "GB",
            "region_name": "United Kingdom",
            "id": "723f5f50-5765-4a13-9689-dfee93b4a4df"
        }
    ],
    "notices": [],
    "model_version": "36",
    "data_version": "33"
}

Notice

The notices array can contain these objects:

Notice attributes
severity string
Either warning or info. warning is for messages that might lead to inaccurate calculations. You should check these to make sure the results are fit for your intended purpose. info is for information that will help you understand the calculation result better.
message string
An explanation of the notice.
code string
A programmatic value you can use to disambiguate the different notice types.

The different possible values for code are as follows. You should not treat this list as exhaustive as more values may be added with time:

Notice Code ValueDescription
emission_factor_region_fallbackEstimation or suggestion used an emission factor from a different region due to data not being available for the region specified in your request.
inflation_appliedInflation was successfully applied to a money-based estimate. The message states the magnitude applied, for example Inflation adjustment of 6.03% applied between 2023 and 2022.
large_inflation_adjustmentInflation was applied over a span of more than 2 years. The message states the magnitude and cautions that compounding inflation over a longer period is less accurate.
partial_inflation_adjustmentInflation was applied, but data was missing for some of the years in the span, so the adjustment only partially covers the period.
no_inflation_adjustmentNo inflation adjustment was made and the estimate is returned unchanged. This is informational when the estimate is not money-based, and a warning when inflation data is unavailable for the emission factor’s country or year range.
Last updated on
Mapping AgentMapping Agent v1 (preview 4)