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.
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:
- 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 stringThe custom label you have specified in your dashboard.
custom_mapping.data_versionrequired stringThe Data Version string for this request. You should use
0.0
currently.custom_mapping.sourcestringEmission factor data source name.
custom_mapping.regionstringGeographic region to which the emission factor applies.
custom_mapping.region_fallbackbooleanSet 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 isfalse
.Default Valuefalse
custom_mapping.year_fallbackbooleanSet 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 isfalse
.Default Valuefalse
custom_mapping.yearintegerThe year in which the emission factor is considered most relevant, according to the source.
custom_mapping.source_lca_activitystringThe Life Cycle Assessment (LCA) activity to which this factor is associated.
custom_mapping.calculation_methodstringThe 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 stringsA 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:
- 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 stringThe 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 stringsThe Climatiq unit types which are acceptable for automatic mapping suggestions to be selected from.
Default ValueAll sources allowedlabels[x].sourcearray of stringsThe sources which are acceptable for automatic mapping suggestions to be selected from.
Default ValueAll sources allowedlabels[x].allow_duplicatesbooleanSet this flag to
false
to avoid creating duplicates of mappings.Default Valuetrue
- data_versionrequired string
The required Data Version string within which activities will be sought to match the labels.
Default Value0.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.
- 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" }]