Private Emission Factors Endpoint version: V1 (preview 1)V1 (preview 1) ADD-ONADD-ON

⚠️

Preview Feature

This feature is currently in preview. That means that we believe the feature is good enough to start using, but:

There might still be bugs or edge cases we haven't covered.
The documentation and error messages might be less detailed.
We might need to make further changes in the API surface.

We need the ability to iterate quickly on preview versions, so we offer less guarantees of stability. When we make changes to the preview version, we will release a new version, and you must migrate to this new version within three months. Read more about API versioning at Climatiq here.For this reason, preview endpoints are not available without explicitly opting in. If you would like to opt-in to this preview feature, please contact us.

Sometimes you may need your own non-public custom emission factors in your project instead of using the wide variety that Climatiq offers - such a licensed dataset or supplier-specific emission factors. The Private Emission Factors Management API provides a way to create, delete and list these kind of emission factors and make them available later to you in the estimate or search endpoints.

The Climatiq Dashboard also offers an interactive way to manage your project’s Private Factors, read our tutorial if you want to know more.

Create a custom private emission factor

POST Creates a new private emission factor for your project.


https://preview.api.climatiq.io/private-data/v1-preview1/private-factors

Request

This endpoint accepts the following parameters.

Request headersRequired HTTP headers for this request

Authorizationrequired string
Bearer token containing your Climatiq API key. Example: Authorization: Bearer CLIMATIQ_API_KEY
Don't have an API key? Get your API key here.

Request parametersShould be sent as a JSON object in the body

activity_idrequired string
Represents the activity associated with the emission factor. It can also be used later to perform estimations. It must be an ASCII string. It cannot be empty.
namerequired string
The name of the private emission factor. It must be an UTF-8 string. It cannot be empty.
regionrequired string
Geographic region where the emission factor applies. It must be an ASCII string. It should be a valid region code. For details on how to find the list of available region codes, see this guide.
yearrequired integer
The year in which the emission factor is considered most relevant.
unitrequired string
A unit reference applicable to the factor that determines which units can be used for estimations. See the units table below for supported units.
calculation_methodrequired string
The calculation method that will be used to calculate the CO2e emission factor. Can be either ar4, ar5, or ar6. Learn more about calculation methods here..
co2e_totalrequired number
The total amount of GHG emitted per unit of activity, expressed as kgCO2e. The unit is specified in the unit field and determines how emissions are quantified.
source_lca_activityrequired string
The Life Cycle Assessment (LCA) activity to which this factor is associated. It must be an ASCII string. It can be empty.
sectorrequired string
Emission factor sector name. It must be an ASCII string. It cannot be empty.
categoryrequired string
Category name that the emission factor will be linked to. It must be an ASCII string. It cannot be empty.
uncertaintyinteger
Emission factor uncertainty factor (%).
scopesarray of strings
Default value: All scopes: ['1','2','3.1','3.2','3.3','3.4','3.5','3.6','3.7','3.8','3.9','3.10','3.11','3.12','3.13','3.14','3.15']
The Greenhouse Gas Protocol scopes that this emission factor can be used for. If not provided, or an empty array is provided, the emission factor will be applicable to be used under all scopes.
Default Value
All scopes: ['1','2','3.1','3.2','3.3','3.4','3.5','3.6','3.7','3.8','3.9','3.10','3.11','3.12','3.13','3.14','3.15']
sourcerequired string
Emission factor data source name. It must be an ASCII string. It can be empty.
descriptionrequired string
A short description for the emission factor. It must be an UTF-8 string. It can be empty.
source_linkrequired string
URL to the source for reference. It must be an ASCII string. It can be empty.


curl --request POST \
  --url https://preview.api.climatiq.io/private-data/v1-preview1/private-factors \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
  --data '{
    "activity_id": "my_private_factor_id",
    "name": "My Private Factor",
    "region": "US",
    "year": 2023,
    "unit": "mile",
    "calculation_method": "ar5",
    "co2e_total": 123.45,
    "source_lca_activity": "manufacturing_process",
    "sector": "Energy",
    "category": "Power Generation",
    "uncertainty": 10,
    "source": "Sample Source",
    "description": "Example factor for demonstration purposes",
    "source_link": "https://example.com/emission-factor"
}'

Response

If the private factors was successfully uploaded, you will receive the same object provided in the request, with an additional attribute: the ID of the emission factor, which can be used for future estimations.

Response parameters

idstring
The ID of the new private factor. It can be used later to operate on the emission factor.
activity_idstring
Represents the activity associated with the emission factor. This ID can also be used in estimations.
namestring
The name of the private emission factor
regionstring
Geographic region where the emission factor applies.
yearinteger
The year in which the emission factor is considered most relevant.
unitstring
The unit reference applicable to the factor. Can be either mile, passenger-mile, km, passenger-km, tonne-km, ton-mile, tonne, short ton, kg, person-night, room-night, CPU-hour, GB-hour, GB, TB-hour, GJ, kWh, MMBTU, l, m3, gal (US), scf, gbp, usd, eur or number
unit_typestring
The Unit types that this emission factor uses.
calculation_methodstring
The calculation method that will be used to calculate the CO2e emission factor. Can be either ar4, ar5, or ar6. Learn more about calculation methods here..
co2e_totalnumber
The total amount of GHG emitted per unit of activity, expressed as kgCO2e. The unit is specified in the unit field and determines how emissions are quantified.
source_lca_activitystring
The Life Cycle Assessment (LCA) activity to which this factor is associated.
sectorstring
Emission factor data sector name.
categorystring
Category name that the emission factor is linked to.
uncertaintyinteger
Emission factor uncertainty factor (%).
scopesarray of strings
The Greenhouse Gas Protocol scopes that this emission factor can be used for.
sourcestring
Emission factor data source name.
descriptionstring
The factor short description.
source_linkstring
URL to the source for reference.


{
    "id": "62ff713d-780b-4afa-a7cd-b91318c019d4",
    "activity_id": "my_private_factor_id",
    "name": "My Private Factor",
    "region": "US",
    "year": 2023,
    "unit": "mile",
    "unit_type": "Distance",
    "calculation_method": "ar5",
    "co2e_total": 123.5,
    "source_lca_activity": "manufacturing_process",
    "sector": "Energy",
    "category": "Power Generation",
    "uncertainty": 10,
    "scopes": [
        "1",
        "2",
        "3.1",
        "3.2",
        "3.3",
        "3.4",
        "3.5",
        "3.6",
        "3.7",
        "3.8",
        "3.9",
        "3.10",
        "3.11",
        "3.12",
        "3.13",
        "3.14",
        "3.15"
    ],
    "source": "Sample Source",
    "description": "Example factor for demonstration purposes",
    "source_link": "https://example.com/emission-factor"
}

Batch create private emission factors

POST Creates a new set of private emission factors for your project.


https://preview.api.climatiq.io/private-data/v1-preview1/private-factors/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.

Units

The private data feature accepts a list of units that the private factors can have. These units correspond to the most common units from the databases that Climatiq ingresses data from.

Read Units vs Unit Types for a more in-depth description of these units and how they correspond to unit types.

This table lists the most commonly accepted units, and what unit type they can be used with.

Unit	Name	Unit Type
`m`	Meter	`Distance`
`mile`	Mile	`Distance`
`km`	Kilometer	`Distance`
`passenger-mile`	Passenger per mile	`PassengerOverDistance`*
`passenger-km`	Passenger per kilometer	`PassengerOverDistance`*
`tonne-km`	Tonnes per Kilometer	`WeightOverDistance`
`ton-mile`	Tonnes per mile	`WeightOverDistance`
`g`	Gram	`Weight`
`kg`	Kilogram	`Weight`
`tonne`	Metric Tonne	`Weight`
`short ton`	Short ton	`Weight`
`CPU-hour`	CPUs per Hour	`NumberOverTime`
`GB`	Gigabytes	`Data`
`GB-hour`	Gigabytes per hour	`DataOverTime`
`TB-hour`	Terabytes per hour	`DataOverTime`
`MJ`	Megajoules	`Energy`
`GJ`	Gigajoules	`Energy`
`TJ`	Terajoules	`Energy`
`kWh`	kWh	`Energy`
`MMBTU`	1 Million British Thermal Units	`Energy`
`l`	Liter	`Volume`
`ml`	Milliliters	`Volume`
`m3`	Cubic Meters	`Volume`
`gal (US)`	US gallon	`Volume`
`ha`	hectare	`Area`
`m2`	Square Meter	`Area`
`gbp`	British Pound (GBP)	`Money`
`usd`	US Dollar	`Money`
`eur`	Euro	`Money`
`nzd`	New Zealand Dollar	`Money`
`cad`	Canadian Dollar	`Money`
`number`	Number	`Number`
`kg-day`	Kilo per dat	`WeightOverTime`
`ha-year`	Hectare per year	`AreaOverTime`
`m2-year`	Square meters per year	`AreaOverTime`
`kW`	Kilowatt	`Power`
`year`	Year	`Time`

*Note that units that have the PassengerOverDistance unit type can also be used with just the Distance unit type, in which case it is assumed that there is only one passenger.

Delete a private emission factor

DELETE Deletes a private emission factor from your project.


https://preview.api.climatiq.io/private-data/v1-preview1/private-factors/:id

Where the :id path argument must be replaced with the id of the private factor.

List custom private emission factors

GET Retrieve the list of private emission factors in your project.


https://preview.api.climatiq.io/private-data/v1-preview1/private-factors

Request


curl --request GET \
  --url https://preview.api.climatiq.io/private-data/v1-preview1/private-factors \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY"

Response

The response will show an array of private emission factors for the project. Each object matches the schema that is returned from Create a custom private emission factor


[
    {
        "id": "62ff713d-780b-4afa-a7cd-d600f088gg",
        "activity_id": "my_private_factor_id",
        "name": "My Private Factor",
        "region": "US",
        "year": 2023,
        "unit": "mile",
        "unit_type": "Distance",
        "calculation_method": "ar5",
        "co2e_total": 123.5,
        "source_lca_activity": "manufacturing_process",
        "sector": "Energy",
        "category": "Power Generation",
        "uncertainty": 10,
        "scopes": [
                "1",
                "2",
                "3.1",
                "3.2",
                "3.3",
                "3.4",
                "3.5",
                "3.6",
                "3.7",
                "3.8",
                "3.9",
                "3.10",
                "3.11",
                "3.12",
                "3.13",
                "3.14",
                "3.15"
        ],
        "source": "Sample Source",
        "description": "Example factor for demonstration purposes",
        "source_link": "https://example.com/emission-factor"
    },
    ...
]

Estimate

Performing estimations with private emission factors work like estimating with Climatiq-supplied emissions factors. You use the provided Selector to target your own private emission factors. Refer to our Upload and Use Private Emission Factors tutorial for a guide on how to use the Basic Estimate endpoint with private emission factors.