API Reference
Basic Estimate

Estimation Endpoint version: V1V1

Estimation operations are performed to calculate emissions produced by one or more activities, based on multiplying activity data by the appropriate emission factors.

Estimate

POST Calculate total estimated emissions produced for a particular activity, in kgCO2e, using the available emission factors. All requests are performed by sending a POST request to the following endpoint:

https://api.climatiq.io/data/v1/estimate

The method of calculating emission estimates can differ depending on the unit type that the factor accepts and the applicability of the emission factor as indicated in the ID, name and description fields, with further detail provided by the source.

Every factor is linked to a unit type that is specified in the emission factors list inside the unit_type attribute. See all available emission factors in our Data Explorer (opens in a new tab).

Request

This endpoint accepts the following parameters:

Request parametersShould be sent as a JSON object in the body
    • emission_factorrequired Selector

      Emission factor ID or selection parameters selector.

    • parametersrequired Parameters

      Emission factor parameters. The parameter object changes depending on the EF selected.

curl --request POST \
  --url https://api.climatiq.io/data/v1/estimate \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
  --data '{
      "emission_factor": {
        "activity_id": "electricity-supply_grid-source_residual_mix",
        "data_version": "^6"
       },
      "parameters": {
        "energy": 100,
        "energy_unit": "kWh"
      }
  }'

Response

This endpoint returns an Estimate with notices. It has the same field as the Estimation model, but with an additional notices field.

Response parameters
    • co2efloat

      Emission factor carbon dioxide equivalent.

    • co2e_unitstring

      The unit in which the co2e field is expressed.

    • co2e_calculation_methodstring

      Which calculation methodology that was used for the calculation. The value of this is either ar4, ar5 or ar6. Learn more about calculation methods here.

    • co2e_calculation_originstring

      Whether or not the data source or Climatiq made the calculation. The value of this is either source or climatiq. Learn more about calculation methods here.

    • emission_factorused emission factor or null

      The emission factor that was used for the calculation. This might be null if you do not have audit trail enabled.

    • constituent_gasesconstituent gases or null

      Indicates which constituent gases the emission factor is composed of. This might be null if you do not have audit trail enabled.

    • audit_trailaudit trail flag

      Indicates whether Audit trail was enabled for this request. Is one of enabled, disabled or selector.

    • activity_data

      Indicates the parameters which were multiplied by the factor to estimate emissions.

    • noticesarray of Notice

      Lists any notices that are relevant for understanding the result.

{
    "co2e": 81,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ar5",
    "co2e_calculation_origin": "source",
    "emission_factor": {
        "name": "Electricity supplied from grid - residual mix",
        "activity_id": "electricity-supply_grid-source_residual_mix",
        "id": "fa8faa67-e212-48c5-a7ef-074cda9ac5f5",
        "access_type": "public",
        "source": "DISER",
        "source_dataset": "National Greenhouse and Energy Reporting (Measurement) Determination (NGER)",
        "year": 2024,
        "region": "AU-NSW",
        "category": "Electricity",
        "source_lca_activity": "electricity_generation",
        "data_quality_flags": []
    },
    "constituent_gases": {
        "co2e_total": 81,
        "co2e_other": null,
        "co2": null,
        "ch4": null,
        "n2o": null
    },
    "activity_data": {
        "activity_value": 100,
        "activity_unit": "kWh"
    },
    "audit_trail": "selector",
    "notices": []
}

Notice

The notices array can contain these objects:

Notice attributes
severity string
Either warning or info. warning is for messages that might lead to inaccurate calculations. You should check these to make sure the results are fit for your intended purpose. info is for information that will help you understand the calculation result better.
message string
An explanation of the notice.
code string
A programmatic value you can use to disambiguate the different notice types.

The different possible values for code are as follows. You should not treat this list as exhaustive as more values may be added with time:

Notice code valuedescription
exchange_rate_fallbackNot exchange rate data was available for the requested year. The calculations were performed with data for the closest available year. This can only happen when using the private data feature with money-based emission factors.

Batch Estimate Endpoint

POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.

The batch endpoint is available at:

https://api.climatiq.io/data/v1/estimate/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.

Classifications v2 (preview 1)Cloud Computing