Mapping custom identifiers to Climatiq emission factors

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. This often means a laborious process of identifying the right emission factor for each category of activity before getting started with estimations. Typically that mapping information is then put in a spreadsheet somewhere, and is often difficult to find once an initial implementation is complete. Climatiq solves this problem with the Custom Activity Mapping tool, available in the Climatiq dashboard (opens in a new tab). This tool allows Climatiq users to map any identifier they choose to a Climatiq activity ID, which can then be used to make estimates via the Custom Activities 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
• Add your whole taxonomy to Climatiq either via the /custom-activities/labels endpoint (read more here) or upload via our dashboard, then review suggested mappings provided by Climatiq.
• Upload your taxonomy in a csv with Climatiq activity_ids already mapped

Creating a new single mapping

You can click on the “Add new activity button to perform your first mapping.

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

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 Activity Mapping tool.

Click save, and you’ve created your first activity 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.

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-activities/labels endpoint (read more here)

Similarily to when creating a single mapping, you can also filter suggestions that will be showed in the activity mappings table once you have uploaded your CSV file.

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,

Click now on “Select CSV file...“ and select your file from your computer. Choose any source or unit type filter if you need a more accurate suggestion for the second record and click on “Submit“.

Once the file is processed, you will be redirected to the activity 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.

You now need to go through all unmapped records and confirm an activity ID before going live. Click on the edit button and as you did in the previous section, provide a valid Activity ID or accept the suggested one.

Making a query using the Custom Activities endpoint

Now that we have an emission factor mapped to a custom activity label, we can use that label in the Custom Activities 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://beta4.api.climatiq.io/custom-activities/estimate \
 --header 'Authorization: Bearer YOUR_API_KEY' \
 --data
{
   "custom_activity": {
       "label": "IT Equipment",
       "data_version": "^1",
       "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",
        "year": 2021,
        "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
    }
}

This tells me that 233.1 kgCO2e were emitted as a result of this purchase. So now every activity defined as "IT Equipment" will correctly map to the right emission factor, and if it is available across geographies etc. nothing needs to change. So if, for example, another laptop was purchased in the UK for £999 it is simply a matter of changing the region code to “GB”, the money value to 999 and the currency to “gbp” to receive an estimate.

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 with any issues you encounter or ideas you have for improvements.