API Reference
Custom Mappings

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 behavior 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://api.climatiq.io/custom-mappings/v1/estimate

Request

This endpoint accepts the following parameters:

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

      A selector allowing the use of a custom label defined in the custom mapping tab in the Climatiq Dashboard


      custom_mapping.labelrequired string

      The custom label you have specified in your dashboard.


      custom_mapping.data_versionrequired string

      The Data Version string for this request. You should use 0.0 currently.


      custom_mapping.sourcestring

      Emission factor data source name.


      custom_mapping.regionstring

      Geographic region to which the emission factor applies.


      custom_mapping.region_fallbackboolean

      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. Only one fallback can be specified at a time. Default is false.

      Default Value
      false

      custom_mapping.year_fallbackboolean

      Set this to true if you're willing to accept a less specific year than the one you've specified. Climatiq will then attempt to find an emission factor with a year as close as possible to the one you've provided. Only one fallback can be specified at a time. Default is false.

      Default Value
      false

      custom_mapping.yearinteger

      The year in which the emission factor is considered most relevant, according to the source.


      custom_mapping.source_lca_activitystring

      The Life Cycle Assessment (LCA) activity to which this factor is associated.


      custom_mapping.calculation_methodstring

      The calculation method that will be used to calculate the CO2e emission factor. Options are "ar4", "ar5", or "ar6". Learn more about calculation methods here.


      custom_mapping.allowed_data_quality_flagsarray of strings

      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.

    • parametersrequired Parameters object

      Emission factor parameters. The parameter object changes depending on the EF selected.

# 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://api.climatiq.io/custom-mappings/v1/estimate \
--header 'Authorization: Bearer $CLIMATIQ_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 Estimate Endpoint

POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.

The batch endpoint is available at:

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

Provide this endpoint with an array of objects, where each object is a valid body for the non-batch endpoint. See the batch endpoint documentation for more information about how batch endpoints work and how to handle errors.

Custom Mapping Labels

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://api.climatiq.io/custom-mappings/v1/labels

Request

This endpoint accepts the following parameters:

Request parametersShould be sent as a JSON object in the body
    • labelsrequired array of objects

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


      labels[x].labelrequired 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.


      labels[x].unit_typearray of strings

      The Climatiq unit types which are acceptable for automatic mapping suggestions to be selected from.

      Default Value
      All sources allowed

      labels[x].sourcearray of strings

      The sources which are acceptable for automatic mapping suggestions to be selected from.

      Default Value
      All sources allowed

      labels[x].allow_duplicatesboolean

      Set this flag to false to avoid creating duplicates of mappings.

      Default Value
      true
    • data_versionrequired string

      The required Data Version string within which activities will be sought to match the labels.

      Default Value
      0.0
curl --request POST \
--url https://api.climatiq.io/custom-mappings/v1/labels \
--header 'Authorization: Bearer $CLIMATIQ_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.

Response parameters
    • labelstring

      The label used to designate this custom mapping.

    • activity_idstring

      The activity_id that will be suggested in the custom mappings dashboard, if a suitable one has been found.

    • idstring

      The unique ID for this particular mapping.

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