Upload and Use Private Emission Factors

Learn how to create, manage, and use private emission factors with the Climatiq API for custom calculations.

⚠️

Subscription plan required

This is a paid feature. Please see our pricing page for more details.

The Climatiq API provides a wide range of public emission factors, but sometimes you may require custom emission factors for specific activities for your project that can't be shared publicly - say a licensed dataset or footprints provided from suppliers. Climatiq allows you to securely add private emission factors via an uploader in our dashboard, making them available to you right alongside any of the currently available emission factors in our /estimate, /batch and /search endpoints.

Upload Private Emission Factors via the Climatiq Dashboard

Log in to your Climatiq Dashboard.

Click on Add emission factors

This takes you to the file uploader where you can upload your emission factors

(Optional) Download the sample CSV file

Download the template file and replace the single row of dummy data with your emission factors; see Appendix A for a summary of the fields that are accepted by the uploader. Then click “Choose file”, browse to where you have saved the CSV you wish to upload and double click.

Submit the CSV file

Based on the data structure provided in the template file, upload your custom private factors by using the provided form and click Submit

Add private data

Wait for the private emission factors to be validated

The uploader will check the file for errors before adding the emission factors in the file to your list of private emission factors - it will look something like this:

Display private data

Replace a private emission factor

You can replace or change factors simply by selecting the factor and deleting it, then uploading a replacement.

Using Your Private Factors

To use a private emission factor in an estimate:

Make a request to the `/estimate` endpoint.

Make an POST request to the /estimate endpoint including your Emission Factor Activity ID in the activity_id field:

curl --request POST \
    --url https://api.climatiq.io/data/v1/estimate \
    --header 'Authorization: Bearer $CLIMATIQ_API_KEY' \
    --data
    {
        "emission_factor": {
            "activity_id": "other_materials-type_custom_material",
            "data_version": "^3",
            "region": "DE"
        },
        "parameters": {
            "weight": 10,
            "weight_unit": "kg"
        }
    }'

Get the estimation result for your emission factor in the response

{
    "co2e": 72.358,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ar4",
    "co2e_calculation_origin": "source",
    "emission_factor": {
        "name": "Bananas",
        "activity_id": "bananas",
        "id": "192bea15-55d7-4eab-9571-6ca0a2d3dea6",
        "access_type": "private",
        "source": "Climatiq",
        "source_dataset": "",
        "year": 2022,
        "region": "DE",
        "category": "Other Materials",
        "source_lca_activity": "cradle_to_gate",
        "data_quality_flags": []
    },
    "constituent_gases": {
        "co2e_total": null,
        "co2e_other": null,
        "co2": null,
        "ch4": null,
        "n2o": null
    },
    "activity_data": {
        "activity_value": 10.0,
        "activity_unit": "kg"
    },
    "audit_trail": "selector"
}

This reports that 3.4 kgCO2e were emitted as a result of the production of 10 kg of bananas, based on the emission factor uploaded.

Appendix: Data Structure For Private Emission Factors

Summary of the fields that are accepted by the uploader (* denotes required fields; the uploader will check these fields for errors)

Field name.	Description	Values accepted
`name`*	This is the name of the factor as it will appear in your list of private emission factors	String (max. 140 characters).
`activity_id`	This is the primary value that identifies the emission factors, and will be used in requests - see more about formulating requests here.	String (max. 200 characters; alphanumeric characters, decimal points, hyphens and underscores only); if left blank, an ID will be auto-generated based on the name field.
`region`*	Geographic region to which the emission factor applies.	Valid country code (based on UN-LOCODEs (opens in a new tab)).
`year`*	Year for which the emission factor applies.	4 digits.
`activity_unit`*	The unit in which the activity is expressed (e.g. kg or kWh)	A supported unit.
`ar_calculation_method`*	The methodology used to calculate the emission factor (currently IPCC AR4 or AR5)	`ar4` or `ar5`.
`source_lca_activity`	Life cycle assessment activity to which the emission factor applies.	String (max. 40 chars; alphanumeric and underscore only). This is user-defined. If left blank, this will default to `unknown`.
`co2e_total`*	The emission factor value, expressed in kgCO2e.	Float.
`sector`	The overarching category of an emission factor.	String (max. 40 chars; alphanumeric). This is user-defined. It may be left blank.
`category`	The specific category of an emission factor.	String (max. 40 chars; alphanumeric). This is user-defined. It may be left blank.
`source`	The source providing this emission factor.	String (max. 40 characters). This will default to “Private" if left blank.
`source_link`	URL to the source for reference.	String (max. 200 characters). May be left blank.
`uncertainty`	Uncertainty around the emission factor (expressed as %)	Integer (between 0 and 100). May be left blank.
`description`	Descriptive string, giving context and detail about the emission factor.	String (max. 1000 characters). May be left blank.

Quickstart Calculate Cloud Carbon Footprint