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.

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:

# 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:

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.

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