Mapping Custom Identifiers to Climatiq Emission Factors

⚠️

Subscription plan required

This is a paid feature. Please see our pricing page for more details.

Introduction

Perhaps the most important step in any emission calculation exercise is the selection of the right emission factor to use for a given emission-generating activity. Traditionally, this process requires intensive labor to establish the right emission factor for each category of activity. Furthermore, this mapping information often finds itself tucked away in a spreadsheet, making it difficult to locate once the initial setup is done.

Climatiq solves this problem with the Custom Mapping tool, available in the Climatiq dashboard (opens in a new tab). This tool empowers Climatiq users to map any identifier they choose to a Climatiq activity ID, which can then be used for emission estimation via the Custom Mapping endpoint.

This means that there is a persistent place within the Climatiq ecosystem where your activity to emission factor mapping is saved and can be updated at any time, without changing a line of code. Each of your projects can be mapped differently, affording you plenty of flexibility.

Let’s take a look at how it works.

Mapping Your Activities

To get started on your custom map, you can either:

Add mappings one-by-one via our Dashboard (opens in a new tab).
Import your entire taxonomy to Climatiq either via the /custom-mappings/labels endpoint (read more here) or upload via our dashboard, then review suggested mappings provided by Climatiq.
Upload your taxonomy as a CSV file with Climatiq activity_ids already mapped.

Creating a New Single Mapping via the Dashboard

Navigate to the Custom Mappings Screen

To create your first mapping, navigate to the Custom Mappings screen in Climatiq Dashboard (opens in a new tab) and click on the “Add new mapping" button.

Add new activity button

Input a Mapping Label

This will add a line to your mapping table. Type the label you would like to use in to the “Activity label” field.

Empty custom mapping

Await Activity ID Suggestions

As soon as you add it, you may see a suggested Activity ID based on the label that you have chosen for your mapping. You can now accept the suggested activity ID (and save the new mapping), try to refine the suggestion by using the filters below or click one of the links provided to find an Activity ID in our Data Explorer. Once you are happy with the mapping, click "Save changes".

Let's say, for example, that your accounting software has a category called “IT Equipment” and you’d like to automatically map that to an appropriate emission factor without changing anything in your accounting software or associated code. You'd also prefer to map it to an emission factor that comes from the source “EXIOBASE“. You would then write “IT Equipment” into the “activity label” field, select “EXIOBASE“ in the source filter selector and wait for a suggestion. If the suggestion applies to your criteria, then click on “Accept suggestion & save“. Otherwise, follow the links to Climatiq Data Explorer (opens in a new tab) to find right emission factor for this activity in the, then copy it into the Activity ID field in the Custom Mapping tool.

Complete custom mapping

Save the Changes

Click save, and you’ve created your first custom mapping! Note that you might need to wait a minute or two before the changes take effect in the API.

Creating Mappings in Batches

You also have the option to create many mappings at once by uploading a CSV file.

Navigate to the Custom Mappings Uploader

Navigate to the Custom Mappings screen in Climatiq Dashboard (opens in a new tab) and click on the “Upload mappings" button.

Upload activities button

Prepare your CSV file

The CSV file contains two different columns: Activity label and activity ID. Any row in the file that contains an empty activity ID will get a suggested activity ID in return. Note that you can also send unmapped taxonomies via the /custom-mappings/labels endpoint (read more here)

For example, let's say that you need to create two mappings with activity labels “Hardware“ and “IT Equipment“. You already know an activity ID for the first one but not for the latter one so your CSV file would look like this:

activity_label,activity_id
Hardware,consumer_goods-type_domestic_appliances_disposables
IT Equipment,

Upload the CSV File

Click on the "Select CSV file..." button and choose the file from your computer. If you want to narrow down suggestions for labels that are not mapped to an activity ID, you can choose a source or unit type using the filters provided. In return, the uploader will suggest an activity ID for you with these filters applied. Finally, click on the "Submit" button.

Upload a new activities file

Review the Unmapped/Suggested Mappings

Once the file is processed, you will be redirected to the custom mappings table with the new records in it. The first record will be automatically mapped to the specified activity ID in your file. However, the second one will appear as Unmapped. This means that the activity is not yet mapped and not available for estimations when using the API.

If Climatiq was able to find a suggested Activity ID based on the label (“IT Equipment“), the table will give you the choice to accept the suggestion. If it is accepted, the mapping will be saved and the “Unmapped“ status will disappear, meaning that the mapping is ready to use in carbon estimations.

Mappings table with suggestions

The next step is to review all unmapped records and confirm an activity ID. Click on the edit button and either provide a valid Activity ID or accept the suggested one, as you did in the previous section.

Upload Mapping Labels via the Custom Mappings Labels Endpoint

Note that you can also send unmapped records via the /custom-mappings/labels endpoint (read more here). By doing so, the mappings will be stored as “Unmapped“, you can later navigate to the custom mappings table in the Dashboard and follow the same review process described in the previous section.

Making a query using the Custom Mapping endpoint

Now that we have an emission factor mapped to a custom label, we can use that label in the Custom Mapping endpoint to perform emission estimations. For this exercise, we will take as our example “activity” a laptop computer purchased in Germany.

curl --request POST \
 --url https://api.climatiq.io/custom-mappings/v1/estimate \
 --header 'Authorization: Bearer $CLIMATIQ_API_KEY' \
 --data '{
   "custom_activity": {
       "label": "IT Equipment",
       "data_version": "0.0",
       "region": "DE"
     },
     "parameters": {
       "money": 1099,
       "money_unit": "eur"
     }
}'

And you will get the following response back.

{
    "co2e": 233.0979,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ar5",
    "co2e_calculation_origin": "source",
    "emission_factor": {
        "name": "Office machinery and computers",
        "activity_id": "office_equipment-type_office_machinery_computers",
        "id": "382cc9d8-2380-4dc3-8a61-a85cd6146042",
        "access_type": "public",
        "source": "EXIOBASE",
        "source_dataset": "EXIOBASE 3",
        "year": 2019,
        "region": "DE",
        "category": "Office Equipment",
        "source_lca_activity": "unknown",
        "data_quality_flags": []
    },
    "constituent_gases": {
        "co2e_total": 233.0979,
        "co2e_other": null,
        "co2": null,
        "ch4": null,
        "n2o": null
    },
    "activity_data": {
        "activity_value": 1099.0,
        "activity_unit": "eur"
    },
    "audit_trail": "selector"
}

This response indicates that the purchase resulted in 233.1 kgCO2e of emissions. From now on, every activity defined as "IT Equipment" will be correctly mapped to the appropriate emission factor. If the emission factor is available across different geographies, we can estimate emissions for another region using the same custom mapping.

For instance, if another laptop was bought in the UK for £999, you simply adjust the region code to GB, the monetary value to 999, and the currency to gbp to receive an updated estimation.

Summary

We’ve shown you how you can map your own custom identifiers to activity IDs, allowing you to set up and maintain a taxonomy of activities without ever needing to change a line of code, or manage mappings in a spreadsheet or other tool.

Please do get in touch (opens in a new tab) with any issues you encounter or ideas you have for improvements.

Use Classification Codes Apply Life Cycle Assessment Information