Custom Mappings ADD-ONADD-ON

Instead of using code to specify emission factors you want to use for your calculations, you can map your own labels to Climatiq activity IDs in the Climatiq dashboard (opens in a new tab), allowing the Climatiq API to recognize whatever values you use to categorize your activities. In the dashboard simply link a custom mapping label to an activity ID, and this can then be used in the custom mapping endpoints.

This means you can add and manage how your activities map to emission factors without having to update your code. View the how-to guide to be taken step-by-step through creating custom mappings and performing queries.

Data versioning of custom mappings

We are still working on how to use data versioning within custom mappings to be as convenient as possible. We ask that you use custom mapping endpoints only with data version 0.0 for now. Using another data version may lead to unexpected behaviour when we change how data versioning works with custom mappings.

Estimate

POST Calculate total estimated emissions produced for a particular activity in kgCO2e using a custom mapping that you have defined under the Custom Mapping tab inside your Climatiq Dashboard (opens in a new tab).

A custom mapping label provides the same flexibility as the ID it maps to. This can happen when multiple emission factors share an activity ID, or because you have mapped the same label to different emission factor ids.

You can provide parameters to select emission factors by filtering using year, region, data source and more as described in our selector section. If there are multiple emission factors Climatiq will automatically pick the most conservative one.

https://beta4.api.climatiq.io/custom-mappings/estimate

Request

The following parameters can be defined as JSON-encoded body.

Attribute	Required
custom_mapping `Custom Mapping Selector` A selector allowing the use of a custom label defined in the custom mapping tab in the Climatiq Dashboard (opens in a new tab)	required
parameters Parameters Emission factor parameters. The parameter object changes depending on the EF selected.	required

The Custom Mapping Selector is very reminiscent of a Selector with a few differences. It is an object consisting of the following parameters:

Attribute	Required
label string The custom label you have specified in your dashboard.	required
data_version string The required Data Version string for this request.	required use `0.0`
source string Emission factor data source name.	optional
region string Geographic region to which the emission factor applies.	optional
region_fallback boolean Set this to `true` if you're willing to accept a less specific geographical region than the one you've specified. Climatiq will then attempt to fall back to the larger region if it does not find any emission factors with the initial region. Default is `false`	optional
year number The year in which the emission factor is considered most relevant, according to the source.	optional
source_lca_activity string The Life Cycle Assessment (LCA) activity to which this factor is associated.	optional
calculation_method `"ar4"`, `"ar5"` or `"ar6"` The calculation method that will be used to calculate the CO2e emission factor. Learn more about calculation methods here.	optional
allowed_data_quality_flags [string] A list of data quality flags that you are willing to allow for this estimate. See the guide on data quality flags for more information and defaults. You can supply an empty list `[]` if you only want to accept emission factors without detected data quality issues.	optional

# In this example, you have already specified "Hotels and accommodation" as a custom mapping in the dashboard
# and linked it to an emission factor that use the Money unit.
curl --request POST \
  --url https://beta4.api.climatiq.io/custom-mappings/estimate \
  --header 'Authorization: Bearer API_KEY' \
  --data '{
    "custom_activity": {
        "label": "Hotels and accommodation",
        "data_version": "0.0",
        "region": "GB"
      },
      "parameters": {
        "money": 100,
        "money_unit": "gbp"
      }
}'

Response

You will get an Estimation back with the CO2e for the given custom mapping, based on the id that it is mapped to in the Custom Mapping tool in the Climatiq Dashboard (opens in a new tab).

{
    "co2e": 24.7,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ar4",
    "co2e_calculation_origin": "source",
    "emission_factor": {
        "name": "Accommodation services",
        "activity_id": "accommodation_type_accommodation_services",
        "id": "de9e8e96-f7c9-4c98-9263-6f1b5a1f40d0",
        "access_type": "public",
        "source": "BEIS",
        "source_dataset": "UK full dataset including conversion factors by SIC code",
        "year": 2019,
        "region": "GB",
        "category": "Accommodation",
        "source_lca_activity": "unknown",
        "data_quality_flags": []
    },
    "constituent_gases": {
        "co2e_total": 24.7,
        "co2e_other": null,
        "co2": 14.7,
        "ch4": null,
        "n2o": null
    },
    "activity_data": {
        "activity_value": 100.0,
        "activity_unit": "gbp"
    },
    "audit_trail": "selector"
}

Batch Estimations

POST Batch estimations for custom mappings work like regular Batch Estimates, allowing you to calculate multiple emission estimations in a single request, all based on custom mappings in the Climatiq Dashboard (opens in a new tab). Currently limited to maximum 100 operations per request.

https://beta4.api.climatiq.io/custom-mappings/batch

Request

Attribute	Required
array List of custom mapping estimation operations. Every operation should follow the same syntax followed by the custom mapping estimate request object.	required

# In this example, you have already specified "Hotels and accommodation" and "Soda" as custom mappings in the dashboard
# and linked them to emission factors that use the Money unit.
curl --request POST \
  --url https://beta4.api.climatiq.io/custom-mappings/batch \
  --header 'Authorization: Bearer API_KEY' \
  --data '[
    {
        "custom_activity": {
            "label": "Hotels and accommodation",
            "data_version": "0.0",
            "region": "GB"
        },
        "parameters": {
            "money": 100,
            "money_unit": "gbp"
        }
    },
    {
        "custom_activity": {
            "label": "Soda",
            "data_version": "0.0"
        },
        "parameters": {
            "money": 100
        }
    }
]'

Response

The response includes a list of responses, like the regular batch endpoint.

Attribute
results [Estimation] List of results for every operation.

{
    "results": [
        {
            "co2e": 24.7,
            "co2e_unit": "kg",
            "co2e_calculation_method": "ar4",
            "co2e_calculation_origin": "source",
            "emission_factor": {
                "name": "Accommodation services",
                "activity_id": "accommodation_type_accommodation_services",
                "id": "de9e8e96-f7c9-4c98-9263-6f1b5a1f40d0",
                "access_type": "public",
                "source": "BEIS",
                "source_dataset": "UK full dataset including conversion factors by SIC code",
                "year": 2019,
                "region": "GB",
                "category": "Accommodation",
                "source_lca_activity": "unknown",
                "data_quality_flags": []
            },
            "constituent_gases": {
                "co2e_total": 24.7,
                "co2e_other": null,
                "co2": 14.7,
                "ch4": null,
                "n2o": null
            },
            "activity_data": {
                "activity_value": 100.0,
                "activity_unit": "gbp"
            },
            "audit_trail": "selector"
        },
        {
            "co2e": 44.4,
            "co2e_unit": "kg",
            "co2e_calculation_method": "ar4",
            "co2e_calculation_origin": "climatiq",
            "emission_factor": {
                "name": "Soft drinks/bottled water and ice",
                "activity_id": "consumer_goods-type_soft_drinks_bottled_water_ice",
                "id": "f403f5a3-2bc4-4d94-b61a-63bc273bc650",
                "access_type": "public",
                "source": "EPA",
                "source_dataset": "Supply Chain Factors Dataset (commodities)",
                "year": 2018,
                "region": "US",
                "category": "Food/Beverages/Tobacco",
                "source_lca_activity": "cradle_to_shelf",
                "data_quality_flags": []
            },
            "constituent_gases": {
                "co2e_total": null,
                "co2e_other": 2.4,
                "co2": 37.0,
                "ch4": 0.2,
                "n2o": 0.0
            },
            "activity_data": {
                "activity_value": 100.0,
                "activity_unit": "usd"
            },
            "audit_trail": "selector"
        }
    ]
}

Custom Mapping Labels ALPHAALPHA

POST Adds new unmapped labels for custom mappings to the project, that the provided API key belongs to.

This will create pending mappings on the project which can be completed in the Climatiq Dashboard, where suggestions will be provided for automatic mapping.

https://beta4.api.climatiq.io/custom-mappings/labels

Request

The request body consists of a json object:

Attribute	Required	Default
labels array The label used to designate your custom mapping. Does not need to be unique, as you can map the same label to multiple of Climatiq's activities	required
data_version string The required Data Version string within which activities will be sought to match the labels.	required use `0.0`

The following parameters can be defined for each of the JSON-encoded objects in the labels array. unit_type and source are optional and used as filters for Climatiq to use when suggesting activities to map to your labels, you can change this later in the dashboard.

Attribute	Required	Default
label string The label used to designate your custom mapping. Does not need to be unique, as you can map the same label to multiple of Climatiq's activities	required
unit_type [string] The Climatiq unit types which are acceptable for automatic mapping suggestions to be selected from.	optional	All
source [string] The sources which are acceptable for automatic mapping suggestions to be selected from.	optional	All
allow_duplicates boolean Set this flag to `false` to avoid creating duplicates of mappings.	optional	true

curl --request POST \
--url https://beta4.api.climatiq.io/custom-mappings/labels \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "data_version": "0.0",
  "labels": [
    {
        "label": "hotel room",
        "source": ["BEIS"]
    },
    {
        "label": "Electricity generation"
    }
  ]
}'

Response

The response will show an array of the newly created pending mappings, including a suggested activity_id if one is found. These mappings are not ready to be used until a user with access to this project visits the Climatiq dashboard and completes the mapping. Any ignored mappings (due to use of the allow_duplicates field) will not be included.

Attribute
label string The label used to designate this custom mapping.
activity_id string The `activity_id` that will be suggested in the custom mappings dashboard, if a suitable one has been found.
id string The unique ID for this particular mapping.

[
    {
        "label": "hotel",
        "activity_id": "accommodation_type_hotel_room",
        "id": "35354707520"
    }
]

Travel Cloud Computing