Mapping Custom Identifiers to earthemission Emission Factors

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.

earthemission solves this problem with the Custom Mapping tool, available in the earthemission dashboard. This tool empowers earthemission users to map any identifier they choose to a earthemission 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 earthemission 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.
Import your entire taxonomy to earthemission either via the /custom-mappings/labels endpoint
Upload your taxonomy as a CSV file with earthemission 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 earthemission Dashboard and click on the “Add new mapping" 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.
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 earthemission Data Explorer to find right emission factor for this activity in the, then copy it into the Activity ID field in the Custom Mapping tool.

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 earthemission Dashboard and click on the “Upload mappings" 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.
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 earthemission 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. 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://beta4.api.earthemission.io/custom-mappings/estimate \
 --header 'Authorization: Bearer YOUR_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 with any issues you encounter or ideas you have for improvements.