API Reference
Procurement

Procurement ADD-ONADD-ON

Spend-based estimations enable carbon footprint calculations for purchased goods and services (GHG Protocol Category 3.1) using expenditure data. They are especially valuable when precise activity data is not readily available. However, the application of spend-based emission factors can be complex. Some emission factor sources, like the UK-specific BEIS spend-based dataset, use the purchaser price directly. On the other hand, sources like EXIOBASE, the most popular provider of spend emission factors, call for the use of the basic price. It's essential to apply the basic price with EXIOBASE emission factors, as using purchaser prices may result in an overestimation of the calculated footprint.

Understanding Basic Price and Purchaser Prices

The basic price represents the initial cost set by a producer for a product or service, without additional fees like taxes or delivery costs (referred to as tax and transport margins). Trade margins and additional charges are often added to the basic price if you're not buying directly from the producer. The purchaser price, the total amount you usually pay, combines the basic price, trade margin, tax margin, and transport margin.

Another challenge with spend-based emission calculations is accurately adjusting for changes in currency exchange rates and inflation. Particularly, when your expenditure occurred in a different year than the emission factor's year, your expenditure amount has to be adjusted to match that emission factor's year. This requires taking into account both inflation adjustment and exchange rate fluctuations to arrive at the adjusted spend amount.

Procurement Endpoint

POST This endpoint automatically calculates basic prices for use with EXIOBASE (opens in a new tab). The endpoint accounts for tax, trade and transport margins using per-sector and per-country margins from EXIOBASE, if no user-supplied margins are provided. The endpoint also corrects for currency exchange rates and inflation adjustments, using rates from the UN Treasury, the IRS and the World Bank, supplemented with per-industry inflation numbers from Eurostat.

Note on EXIOBASE Margins

EXIOBASE margins are experimental and are subject to potentially significant uncertainties. They're a good starting point if you don't have specific margin data. However, if you have custom margin values, we recommend using them for precise results. Not taking margins into account at all will lead to overestimation of your emissions.

https://api.climatiq.io/procurement/v1/spend

Request

This endpoint accepts the following parameters:

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

      The activity associated with the spending. You may specify either a classification code and classification type, or an activity ID.

    • spend_yearrequired integer

      The year when the goods or the services were purchased.

    • spend_regionrequired string

      The UN/LOCODE of the region where the expenditure occurs. For the most accurate results, specify the country of production as the spend_region. If unknown, the country of purchase should be used. Remember that you will need to add transport emissions if the product is shipped from the spend_region to another location.

    • moneyrequired float

      The amount of money spent.

    • money_unitrequired string

      The currency in which the money amount is expressed, in any of the supported currencies.

    • tax_marginfloat
      Default value: Margin extracted from EXIOBASE

      The contribution of tax margins to the final purchaser price. Should be a number below 1, representing 100% contribution. Tax margins can be negative in the case of subsidies.

    • trade_marginfloat
      Default value: Margin extracted from EXIOBASE

      The contribution of trade margins to final purchaser price. Should be a number greater or equal to 0 but lesser than 1, representing 0% and 100% contribution respectively.

    • transport_marginfloat
      Default value: Margin extracted from EXIOBASE

      The contribution of transport margins to the final purchaser price. Should be a greater or equal to 0 but lesser than 1, representing 0% and 100% contribution respectively.

ActivityDescription

You can describe the activity either by using a classification code and classification scheme, or an activity ID.

Classification Code
  • classification_coderequired string

    The classification code.

  • classification_typerequired string

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

Activity ID
  • activity_idrequired string

    The EXIOBASE activity ID for the activity

curl --request POST \
--url https://api.climatiq.io/procurement/v1/spend \
--header "Authorization: Bearer $CLIMATIQ_API_KEY" \
--data '{
"activity": {
"classification_code": "25",
"classification_type": "isic4"
},
"spend_year": 2022,
"spend_region": "DE",
"money": 100,
"money_unit": "eur",
"tax_margin": 0.2
}'

Response

The response includes the CO2e estimate and details about the calculation.

Response parameters
    • estimateEstimation object

      The estimation performed returning the total CO2e value, constituent gases and more.

    • calculation_detailsobject

      Details about the calculation, including applied tax, trade, and transport margins and inflation. Note that this is only returned if audit trail is enabled, otherwise it is null.


      calculation_details[x].tax_marginnumber

      Details about the calculation, including applied tax, trade, and transport margins and inflation. Note that this is only returned if audit trail is enabled, otherwise it is null.


      calculation_details[x].trade_marginnumber

      The trade margin applied in the calculation.


      calculation_details[x].transport_marginnumber

      The transport margin applied in the calculation.


      calculation_details[x].inflation_appliednumber

      The compound inflation applied in the calculation. This is e.g. 0.17 if 17% inflation occurred between the emission factor and spend year. Climatiq will automatically apply inflation or deflation depending on the years.

    • noticesarray of Notices

      Any notices related to the calculation.

    • source_trailarray of Source Data Point

      An array of Source Data Points that help explain and provide trust in the calculation. Click to view more details about Source Trail.

{
"estimate": {
"co2e": 15.66,
"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": "f30ce73e-6f49-46ac-8840-c0bee742164c",
"access_type": "public",
"source": "EXIOBASE",
"source_dataset": "EXIOBASE 3",
"year": 2019,
"region": "DE",
"category": "Fabricated Metal Products",
"source_lca_activity": "unknown",
"data_quality_flags": []
},
"constituent_gases": {
"co2e_total": 15.66,
"co2e_other": null,
"co2": null,
"ch4": null,
"n2o": null
},
"activity_data": {
"activity_value": 61.03,
"activity_unit": "eur"
},
"audit_trail": "enabled"
},
"calculation_details": {
"tax_margin": 0.2,
"trade_margin": 0.09792972014,
"transport_margin": 0,
"inflation_applied": 0.15036269600000027
},
"notices": [],
"source_trail": [
{
"data_category": null,
"name": "Average trade margins for spend type",
"source": "EXIOBASE",
"source_dataset": null,
"year": null,
"region": "DE",
"region_name": "Germany"
},
{
"data_category": null,
"name": "Average transport margins for spend type",
"source": "EXIOBASE",
"source_dataset": null,
"year": null,
"region": "DE",
"region_name": "Germany"
},
{
"data_category": null,
"name": "Industry-specific inflation rates",
"source": "EUROSTAT",
"source_dataset": null,
"year": null,
"region": "DE",
"region_name": "Germany"
},
{
"data_category": "emission_factor",
"name": "Fabricated metal products/except machinery and equipment",
"source": "EXIOBASE",
"source_dataset": "EXIOBASE 3",
"year": "2019",
"region": "DE",
"region_name": "Germany"
}
]
}

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
partial_inflation_adjustmentInflation adjustment was applied only partially, not covering the entire period.
no_inflation_adjustmentNo inflation adjustment was made to the procurement. This could be because there is no data for the spend_country or inflation data is missing for the entire period.
trade_margin_not_appliedNo valid tax margin was found to apply to the procurement's basic price.
tax_margin_not_appliedNo valid tax margin was found to apply to the procurement's basic price.
transport_margin_not_appliedNo valid tax margin was found to apply to the procurement's basic price.

Batch Procurement 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/procurement/v1/spend/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.