API Reference
Classifications v2 (preview 1)

Classifications v2 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 one month. 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.

⚠️
Read the guide or changelog first

This is the API reference for the classifications feature.

If you're just getting started, we highly recommend that you start with the guide that explains the concepts you will need to understand to effectively use the endpoint

If you're already using version 1 and are interested in upgrading, we suggest you start with the changelog which highlights which sections of this document to concentrate on.

Many sources link emission factors (opens in a new tab) to specific industry classification schemes, and Climatiq makes it possible to select an emission factor based on these industry classification codes. Please see below the list of mappings we currently support, with the datasets that are mapped directly to them (note that the API will also map factors indirectly via the UN correspondence tables (opens in a new tab)):

Industry Classification codePrimary dataset
NACE Rev. 2 (opens in a new tab)EXIOBASE3 (opens in a new tab)
Merchant Classification Codes (MCCs) (opens in a new tab)EXIOBASE3 (opens in a new tab)
United Nations Standard Products and Services Code (UNSPSC) (opens in a new tab)EXIOBASE3 (opens in a new tab)
North American Industry Classification System (NAICS) (opens in a new tab)U.S. Government (EPA) (opens in a new tab)

For a more in-depth view on how Climatiq works with classification schemes, view the classification guide.

Estimate

POST Calculate total estimated emissions produced for a particular activity, as described by an industry classification scheme such as ISIC (opens in a new tab) or NACE (opens in a new tab). All requests are performed by sending a POST request to the following endpoint:

https://api.climatiq.io/classifications/v2-preview1/estimate

This endpoint lets you specify an industry classification code and have Climatiq automatically select the appropriate emission factor.

One industry code might be linked to more than one emission factor. If that happens, Climatiq will automatically select the most conservative emission factor. If you would like to specify exactly what emission factor to use, you can specify other attributes to filter on, such as year, source or region.

Industry classification codes can also be mapped to each other using the UN correspondence tables (opens in a new tab), allowing Climatiq to return emission factors from other classification schemes that represent the same activity if there isn't one found directly; this may happen for example because of different classification taxonomies being used in different geographies or by different data sources.

As with any estimation endpoint, the emission factor must be provided with parameters, such as weight, volume, energy. These are provided through the parameters field. See the estimate endpoint for more details on how parameters and units work.

Request

This endpoint accepts the following parameters:

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

      A selector with classification data


      classification.classification_coderequired string

      The classification code.


      classification.classification_typerequired string

      The classification scheme; currently supported are nace2, isic4, mcc, naics2017, or unspsc.


      classification.data_versionrequired string

      The required Data Version string for this request.


      classification.sourcestring

      Emission factor data source name.


      classification.source_datasetstring

      The name of the dataset the source published this emission factor under.


      classification.regionstring

      Geographic region to which the emission factor applies.


      classification.region_fallbackboolean

      Set this to true if you're willing to accept a less specific geographical region than the one you've specified. Climatiq will then attempt to fall back to the larger region if it does not find any emission factors with the initial region. Only one fallback can be specified at a time. Default is false

      Default Value
      false

      classification.year_fallbackboolean

      Set this to true if you're willing to accept a less specific year than the one you've specified. Climatiq will then attempt to find an emission factor with a year as close as possible to the one you've provided. Only one fallback can be specified at a time. Default is false

      Default Value
      false

      classification.yearinteger

      The year in which the emission factor is considered most relevant, according to the source.


      classification.source_lca_activitystring

      The Life Cycle Assessment (LCA) activity to which this factor is associated.


      classification.calculation_methodstring

      The calculation method that will be used to calculate the CO2e emission factor. Learn more about calculation methods here.. Valid values are "ar4", "ar5" or "ar6"


      classification.allowed_data_quality_flagsarray of strings

      A list of data quality flags that you are willing to allow for this estimate. See the guide on data quality flags for more information and defaults. You can supply an empty list [] if you only want to accept emission factors without detected data quality issues.

    • parametersrequired Parameters object

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

curl --request POST \
--url https://api.climatiq.io/classifications/v2-preview1/estimate \
--header "Authorization: Bearer $CLIMATIQ_API_KEY" \
--data '{
"classification": {
"classification_type": "isic4",
"classification_code": "25",
"source": "EXIOBASE"
},
"parameters": {
"money": 25.0,
"money_unit": "usd"
}
}'

Response

This endpoint returns an EstimationWithSourceTrail, which includes the total amount of emissions in kgCO2e and the emission factor used to calculate the emissions.

Response parameters
{
"co2e": 49.25,
"co2e_unit": "kg",
"co2e_calculation_method": "ar5",
"co2e_calculation_origin": "source",
"emission_factor": {
"name": "Fabricated metal products/except machinery and equipment",
"activity_id": "metal_products-type_fabricated_metal_products_except_machinery_equipment",
"id": "79e87731-dc29-470b-a2fa-73e30797bc53",
"access_type": "public",
"source": "EXIOBASE",
"source_dataset": "EXIOBASE 3",
"year": 2019,
"region": "IN",
"category": "Fabricated Metal Products",
"source_lca_activity": "unknown",
"data_quality_flags": []
},
"constituent_gases": {
"co2e_total": 49.25,
"co2e_other": null,
"co2": null,
"ch4": null,
"n2o": null
},
"activity_data": {
"activity_value": 22.35,
"activity_unit": "eur"
},
"audit_trail": "enabled",
"source_trail": [
{
"data_category": "emission_factor",
"name": "Fabricated metal products/except machinery and equipment",
"source": "EXIOBASE",
"source_dataset": "EXIOBASE 3",
"year": "2019",
"region": "IN",
"region_name": "India"
}
]
}