Private Emission Factors (preview 1) ADD-ONADD-ON
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.
- 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
ornumber
- calculation_methodrequired string
The calculation method that will be used to calculate the CO2e emission factor. Can be either
ar4
,ar5
, orar6
. 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.
- 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
ornumber
- calculation_methodstring
The calculation method that will be used to calculate the CO2e emission factor. Can be either
ar4
,ar5
, orar6
. 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.