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 (opens in a new tab) - 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 (opens in a new tab) 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 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 can be empty.
namerequired string
The name of the private emission factor. It must be an ASCII string. It can be empty.
regionrequired string
Geographic region where the emission factor applies. It must be an ASCII string. It can be empty.
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. 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
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.
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 can be empty.
categoryrequired string
Category name that the emission factor will be linked to. It must be an ASCII string. It can be empty.
uncertaintyinteger
Emission factor uncertainty factor (%).
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 ASCII 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,
    "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
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 (%).
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",
    "calculation_method": "ar5",
    "co2e_total": 123.5,
    "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"
}

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.

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",
        "calculation_method": "ar5",
        "co2e_total": 123.5,
        "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"
    },
    ...
]

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.

Management Freight