Understand the difference between source units and unit types

In the Climatiq API there are two similar but distinct concepts: source units and unit types.

Here's an example from the search endpoint that shows both values:

{
    "name": "Hotel stay",
    "description": "Emission intensity of average hotel night in Andorra.",
    "unit_type": "Number",
    "unit": "kg/room-night"
    // ...
}

Notice how we have two fields that are named similarly:

• The unit field shows the source unit "kg/room-night", meaning "kg of CO2e emitted per night spent in a hotel room". This unit comes directly from the publisher of the emission factor, and is the original unit the emission factor was published with.
• The unit_type field is the unit type. Climatiq maps the part after kg/ of the source unit to an overall type - in this case "Number". This describes what types of units you can use to perform estimates with the factor. All unit types are listed in the unit types endpoint.

Why Climatiq separates these concepts

Climatiq decouples the source unit (the unit field above) that each emission factor is provided in, from the unit type you use to interact with it.

This separation has two advantages:

• Many source units map to one unit type: The Number unit type covers very diverse source units, ranging from "hotel nights" to "containers moved".
• You can use different units than the source unit: If an emission factor has "unit": "kg/mile" as its source unit, it will have "unit_type": "Distance". Since the Distance unit type supports both kilometers and miles, you can send your data in whatever unit you have available, and let Climatiq handle the conversion.

To summarize the distinction between the two concepts:

• Unit types are what Climatiq accepts as input for estimates. These are the standardized categories you see in our unit types endpoint - things like "Number", "Money", "Weight", or "WeightOverDistance".
• Source units are what the original emission factors actually measure. These come straight from the data sources and can be very specific - "room-night", "mmbtu", "tonne-km", whatever the emission factor was published with.

Generally when interacting with the API, you primarily care about the unit_type.

When to use the unit field

While the unit_type is generally the most useful of the two, the unit field is relevant for some scenarios, such as:

• Understanding the original emission factor, or cross-referencing with the source.
• The activity_data object returned in many estimations will return the final value, expressed in the source unit. This can be good to save for double-checking or for auditing purposes.

"activity_data": {
    "activity_value": 1.0,
    "activity_unit": "room-night"
}

• When using the search endpoint to get the raw emission factor values. These will be expressed in the source units of the emission factor, so you will need that to handle any conversions.