# Table of Contents
- [Documentation - Automated Carbon Emission Calculations](#documentation-automated-carbon-emission-calculations)
- [Climatiq Guides - Climatiq How-To Guides - Automated Carbon Emission Calculations](#climatiq-guides-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Getting Started - Climatiq API Reference - Automated Carbon Emission Calculations](#getting-started-climatiq-api-reference-automated-carbon-emission-calculations)
- [Quickstart - Climatiq How-To Guides - Automated Carbon Emission Calculations](#quickstart-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Estimation - Climatiq API Reference - Automated Carbon Emission Calculations](#estimation-climatiq-api-reference-automated-carbon-emission-calculations)
- [Search - Climatiq API Reference - Automated Carbon Emission Calculations](#search-climatiq-api-reference-automated-carbon-emission-calculations)
- [Authentication - Climatiq API Reference - Automated Carbon Emission Calculations](#authentication-climatiq-api-reference-automated-carbon-emission-calculations)
- [Intermodal Freight v2 - Climatiq API Reference - Automated Carbon Emission Calculations](#intermodal-freight-v2-climatiq-api-reference-automated-carbon-emission-calculations)
- [How to calculate the carbon emission of your cloud services - Climatiq How-To Guides - Automated Carbon Emission Calculations](#how-to-calculate-the-carbon-emission-of-your-cloud-services-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Upload and Use Private Emission Factors - Climatiq How-To Guides - Automated Carbon Emission Calculations](#upload-and-use-private-emission-factors-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Procurement - Climatiq API Reference - Automated Carbon Emission Calculations](#procurement-climatiq-api-reference-automated-carbon-emission-calculations)
- [Travel - Climatiq API Reference - Automated Carbon Emission Calculations](#travel-climatiq-api-reference-automated-carbon-emission-calculations)
- [Cloud Computing - Climatiq API Reference - Automated Carbon Emission Calculations](#cloud-computing-climatiq-api-reference-automated-carbon-emission-calculations)
- [Using Classification Codes to Estimate Carbon Emissions - Climatiq How-To Guides - Automated Carbon Emission Calculations](#using-classification-codes-to-estimate-carbon-emissions-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Mapping Custom Identifiers to Climatiq Emission Factors - Climatiq How-To Guides - Automated Carbon Emission Calculations](#mapping-custom-identifiers-to-climatiq-emission-factors-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Using source_lca_activity with Climatiq - Climatiq How-To Guides - Automated Carbon Emission Calculations](#using-source-lca-activity-with-climatiq-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Classifications - Climatiq API Reference - Automated Carbon Emission Calculations](#classifications-climatiq-api-reference-automated-carbon-emission-calculations)
- [Custom Mappings - Climatiq API Reference - Automated Carbon Emission Calculations](#custom-mappings-climatiq-api-reference-automated-carbon-emission-calculations)
- [Intermodal Freight Transportation v2 - Climatiq How-To Guides - Automated Carbon Emission Calculations](#intermodal-freight-transportation-v2-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Intermodal Freight Transportation V1 - Climatiq How-To Guides - Automated Carbon Emission Calculations](#intermodal-freight-transportation-v1-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [CBAM - Climatiq API Reference - Automated Carbon Emission Calculations](#cbam-climatiq-api-reference-automated-carbon-emission-calculations)
- [Guide to the Google Sheets Extension - Climatiq How-To Guides - Automated Carbon Emission Calculations](#guide-to-the-google-sheets-extension-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Energy v1 - Climatiq API Reference - Automated Carbon Emission Calculations](#energy-v1-climatiq-api-reference-automated-carbon-emission-calculations)
- [Guide to the Microsoft Excel Add-In - Climatiq How-To Guides - Automated Carbon Emission Calculations](#guide-to-the-microsoft-excel-add-in-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Autopilot Integration Guide - Climatiq How-To Guides - Automated Carbon Emission Calculations](#autopilot-integration-guide-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Autopilot (preview 3) - Climatiq API Reference - Automated Carbon Emission Calculations](#autopilot-preview-3-climatiq-api-reference-automated-carbon-emission-calculations)
- [How to Get A Climatiq API Key - Climatiq How-To Guides - Automated Carbon Emission Calculations](#how-to-get-a-climatiq-api-key-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Postman Collection - Climatiq How-To Guides - Automated Carbon Emission Calculations](#postman-collection-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [What is an Emission Factor? - Climatiq How-To Guides - Automated Carbon Emission Calculations](#what-is-an-emission-factor-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Interacting with the Climatiq API using Python - Climatiq How-To Guides - Automated Carbon Emission Calculations](#interacting-with-the-climatiq-api-using-python-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Calculating Scope 3.1 Emissions with Climatiq’s Procurement Endpoint - Climatiq How-To Guides - Automated Carbon Emission Calculations](#calculating-scope-3-1-emissions-with-climatiq-s-procurement-endpoint-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Fuel and Energy Related Activities (FERA) or upstream / scope 3 - Climatiq How-To Guides - Automated Carbon Emission Calculations](#fuel-and-energy-related-activities-fera-or-upstream-scope-3-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [How to List Metadata and Refine Searches - Climatiq How-To Guides - Automated Carbon Emission Calculations](#how-to-list-metadata-and-refine-searches-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [What Is An Activity ID? - Climatiq How-To Guides - Automated Carbon Emission Calculations](#what-is-an-activity-id-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [CO2e - Methods of Calculation - Climatiq How-To Guides - Automated Carbon Emission Calculations](#co2e-methods-of-calculation-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [API Models - Climatiq API Reference - Automated Carbon Emission Calculations](#api-models-climatiq-api-reference-automated-carbon-emission-calculations)
- [How Climatiq handles data quality - Climatiq How-To Guides - Automated Carbon Emission Calculations](#how-climatiq-handles-data-quality-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [How Climatiq handles currencies - Climatiq How-To Guides - Automated Carbon Emission Calculations](#how-climatiq-handles-currencies-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Data Version Guide - Climatiq How-To Guides - Automated Carbon Emission Calculations](#data-version-guide-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Selector - Climatiq API Reference - Automated Carbon Emission Calculations](#selector-climatiq-api-reference-automated-carbon-emission-calculations)
- [API Versioning - Climatiq How-To Guides - Automated Carbon Emission Calculations](#api-versioning-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Audit Trail - Climatiq API Reference - Automated Carbon Emission Calculations](#audit-trail-climatiq-api-reference-automated-carbon-emission-calculations)
- [Calculating Scope 3.6 Emissions with Climatiq's Travel feature - Climatiq How-To Guides - Automated Carbon Emission Calculations](#calculating-scope-3-6-emissions-with-climatiq-s-travel-feature-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Freight v2 and ISO 14083 compliance - Climatiq How-To Guides - Automated Carbon Emission Calculations](#freight-v2-and-iso-14083-compliance-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Source Trail - Climatiq API Reference - Automated Carbon Emission Calculations](#source-trail-climatiq-api-reference-automated-carbon-emission-calculations)
- [A quick guide to Lifecycle Assessments and using Climatiq for product and corporate reporting - Climatiq How-To Guides - Automated Carbon Emission Calculations](#a-quick-guide-to-lifecycle-assessments-and-using-climatiq-for-product-and-corporate-reporting-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Biogenic CO2 and accounting concepts - Climatiq How-To Guides - Automated Carbon Emission Calculations](#biogenic-co2-and-accounting-concepts-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [A guide to fuel activity_id - Climatiq How-To Guides - Automated Carbon Emission Calculations](#a-guide-to-fuel-activity-id-climatiq-how-to-guides-automated-carbon-emission-calculations)
- [Regions - Climatiq API Reference - Automated Carbon Emission Calculations](#regions-climatiq-api-reference-automated-carbon-emission-calculations)
- [Batch Endpoints - Climatiq API Reference - Automated Carbon Emission Calculations](#batch-endpoints-climatiq-api-reference-automated-carbon-emission-calculations)
- [Errors - Climatiq API Reference - Automated Carbon Emission Calculations](#errors-climatiq-api-reference-automated-carbon-emission-calculations)
---
# Documentation - Automated Carbon Emission Calculations
Documentation
=============
Climatiq simplifies the process of calculating your environmental footprint. We help you understand your impact on the environment by converting your operational activity data into CO2e estimates. With our REST API, you can easily integrate Climatiq into your software and systems and automatically generate CO2e values using scientifically validated emission factors from the Climatiq database.
[Quickstart\
\
Make your first CO2e estimate with the Climatiq API.](/docs/guides/tutorials/quickstart)
[API Reference\
\
Look through this guide to see how our API can be integrated into your product or application.](/docs/api-reference)
[Guides\
\
Guides covering a broad variety of topics, from explaining emission factors and life cycle assessments, to explaining how to upgrade data versions or getting the most out of specific endpoints.](/docs/guides)
Features[](#features)
----------------------
Our API has a number of endpoints for searching and estimating emission factors, as well as specific purposes like calculating emissions from [transport using different modes (opens in a new tab)](https://intermodal.climatiq.io)
, or estimating activities classified under industry-specific classification schemes.
[Search\
\
Determine what emission factors are available to be used in your estimates.](/docs/api-reference/search)
[Basic Estimate\
\
Calculate total estimated emissions produced for a particular activity.](/docs/api-reference/estimate)
[Intermodal Freight\
\
Calculate emissions for shipping freight across different modalities, such as air, sea, and road.](/docs/api-reference/intermodal-freight)
[Cloud Computing\
\
Calculate the carbon footprint of the cloud resources you use.](/docs/api-reference/computing)
[Travel\
\
Calculate emissions produced from travel by car, airplane, train, and hotel stays.](/docs/api-reference/travel)
[Procurement\
\
Automate emission calculations for any purchase with built-in logic for inflation adjustments, currency conversions, and automatic adjustments for tax, trade and transport margins.](/docs/api-reference/procurement)
[Classification\
\
Calculate emissions produced for a particular activity, as described by MCC, NACE, UNSPSC, NAICS, or ISIC.](/docs/api-reference/classifications)
[Custom Mappings\
\
Calculate total estimated emissions produced for a particular activity in kgCO2e using a custom mapping.](/docs/api-reference/custom-mappings)
[Energy\
\
Calculate estimated emissions associated with purchased / consumed energy (electricity, heat & steam, and fuel).](/docs/api-reference/energy)
[CBAM\
\
Calculate estimated carbon emissions and cost of carbon certificates for importing goods into the European Union under the new CBAM regulation.](/docs/api-reference/cbam)
[Autopilot\
\
Calculate estimated emissions based on unstructured input, such as receipts or purchase orders.](/docs/api-reference/autopilot)
In-Depth Guides[](#in-depth-guides)
------------------------------------
A collection of tutorials for using some of our advanced endpoints, and guides for understanding how emission factors are calculated.
[What is an Emission Factor?\
\
If you are new to calculating carbon emissions, you might be overwhelmed by all the specific phrases - so get started by learning about the most important one: Emission Factors.](/docs/guides/understanding/what-is-an-emission-factor)
[Calculating Scope 3.1 Emissions with Climatiq’s Procurement Endpoint\
\
Spend-based emission calculations are a common way to estimate emissions for purchased goods and services (GHG Protocol Category 3.1) when detailed activity data is not available. Climatiq can make this easier - learn how.](/docs/guides/understanding/procurement-spend-based-calculations)
[Estimate Scope 3 fuel and energy related activities (FERA)\
\
It can be confusing to calculate fuel and energy related activities for your scope 3 reporting, but here you will find guidance.](/docs/guides/understanding/selecting-electricity-efs-scope-3)
[CO2e calculation methods\
\
What is CO2 equivalents(CO2e) and how are they calculated? Here we explain CO2e, constituent gases and the different calculation methods, such as AR4, AR5 and AR6.](/docs/guides/understanding/co2e-calculation)
[Private emission factors\
\
Learn how Climatiq allows you to upload your own private emission factors and use them.](/docs/guides/tutorials/private-emission-factors)
[Calculate Intermodal Freight Emissions\
\
Calculating emissions for shipping across several different modalities, such as air, sea and road is a complex undertaking - use Climatiq's dedicated endpoint for quick estimations.](/docs/guides/tutorials/intermodal)
[Use common classification codes for quick carbon estimates\
\
Climatiq's out-of-the-box mapping of leading industry classification schemes like ISIC, NACE, NAICS, MCC, and UNSPSC enables you to quickly estimate your spend-based carbon emissions.](/docs/guides/tutorials/classification-codes)
[Using Python to interact with the Climatiq API\
\
The API can be used with any programming language, but here are a few handy snippets to help you get started with Python.](/docs/guides/how-tos/using-python)
Explore More[](#explore-more)
------------------------------
See our emission factor database or try out our demo apps.
[Data Explorer →\
\
Search through our emission factors database in the Data Explorer](https://climatiq.io/data)
[Intermodal Freight Demo →\
\
Test our intermodal endpoint using this demo app to find emissions between two locations.](https://intermodal.climatiq.io)
---
# Climatiq Guides - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Overview
Climatiq Guides
===============
Here you will find a variety of guides.
* Tutorials are learning-oriented and take you through parts of the Climatiq product, while teaching you underway
* How-to's are goal-oriented and teach you how to solve a concrete problem
* The Understand section dives into deeper explanation and help you understand the Climatiq product and the sustainability space better
Tutorials[](#tutorials)
------------------------
[Quickstart\
\
Make your first CO2e estimate with the Climatiq API.](/docs/guides/tutorials/quickstart)
[Autopilot Integration Guide\
\
Integrate Autopilot into your application to automate emission calculation for your users.](/docs/guides/tutorials/autopilot-integration)
[Guide to the Excel Add-In\
\
Easily utilize the Climatiq capabilities through custom functions from within Excel without any engineering skills required.](/docs/guides/tutorials/excel-addin)
[Guide to the Google Sheets Extension\
\
Benefit from custom formulas in Google Sheets to easily calculate emissions for a wide range of business activities.](/docs/guides/tutorials/google-sheets-extension)
[Upload and use private emission factors\
\
Upload and use any emission factors you like in the API, right alongside the validated datasets currently available.](/docs/guides/tutorials/private-emission-factors)
[Calculate cloud carbon footprint\
\
Climatiq can help you calculate the carbon footprint of your cloud usage for the big three cloud providers. Read more here.](/docs/guides/tutorials/cloud)
[Use classification codes to estimate carbon emissions\
\
Learn how you can use standard industry classification codes to automatically calculate your carbon emissions.](/docs/guides/tutorials/classification-codes)
[Map custom identifiers to Climatiq emission factors\
\
The Custom Mapping tool and endpoint makes it easy perform emission estimates using your own identifiers.](/docs/guides/tutorials/custom-mapping-intro)
[Using source\_lca\_activity with Climatiq\
\
Figure out how Climatiq surfaces lifecycle assessments in the database and which one is relevant to your use case.](/docs/guides/tutorials/lca)
[Intermodal Freight Transportation endpoint\
\
How to use Climatiq to calculate emissions for freight transportation covering several different modalities, such as air, sea, rail and road.](/docs/guides/tutorials/intermodal)
How-Tos[](#how-tos)
--------------------
[Get an API Key\
\
An API token is only a few clicks away. Click here if you're not sure how to get one.](/docs/guides/how-tos/getting-api-key)
[Use the Climatiq postman collection\
\
Use our Postman Collection to send example API requests.](/docs/guides/how-tos/postman-collection)
[Using Python to interact with the Climatiq API\
\
The Climatiq API can be used with any programming language, but here are a few handy snippets to help you get started with Python, including how to use Climatiq within a Jupyter notebook.](/docs/guides/how-tos/using-python)
[List Metadata and Refine Searches\
\
Step-by-step instructions on how to narrow down your search and get exactly the emission factors you're looking for using metadata (such as sources or regions) in Climatiq's database.](/docs/guides/how-tos/search-refinement)
Understand[](#understand)
--------------------------
[What an emission factor is\
\
Wondering exactly what an emission factor is? Read an introductory guide here.](/docs/guides/understanding/what-is-an-emission-factor)
[The Climatiq activity ID\
\
Understand the concept of Activity ID, what is it for and how it relates to emission factors.](/docs/guides/understanding/what-is-an-activity-id)
[How CO2e calculations work\
\
Need a little primer on the ways CO2e for an activity is calculated from constituent gases? Look no further.](/docs/guides/understanding/co2e-calculation)
[How Climatiq handles data quality\
\
Climatiq sometimes finds emission factors that have data quality issues. See how we handle this, and what information we pass on to our API users.](/docs/guides/understanding/data-quality)
[A quick guide to Lifecycle Assessments\
\
Learn what lifecycle asssessments are and how they can apply to your carbon estimates.](/docs/guides/understanding/lca-activity)
[How to work with different currencies\
\
Climatiq works with over 40 currencies. Read here to learn about how we handle conversion rates and more.](/docs/guides/understanding/currency-support)
[How you can calculate scope 3.1 emissions\
\
A guide on how to calculate scope 3.1 (purchased goods and services) emissions.](/docs/guides/understanding/procurement-spend-based-calculations)
[Data Versioning: How Climatiq handles updates to emission factors\
\
How Climatiq uses data versions to let you choose between stability and recency of results.](/docs/guides/understanding/data-versioning)
[How API versioning works at Climatiq\
\
How Climatiq versions its API, and how long you have to upgrade when a new version is released.](/docs/guides/understanding/api-versioning)
[Choose electricity emission factors for Scope 2\
\
Find out how to select the right emission factor(s) for valid estimations of emissions from electricity usage.](/docs/guides/understanding/selecting-electricity-efs)
[How To Estimate Scope 3 Fuel and Energy Related Activities (FERA) For Electricity, Heat and Steam\
\
Guidance on the methodologies of estimating scope 3 fuel and energy related activities.](/docs/guides/understanding/selecting-electricity-efs-scope-3)
[How to Calculate Emissions from Travel\
\
Understand how Climatiq calculate emissions produced from travel by car, airplane, train, and hotel stays.](/docs/guides/understanding/travel)
[Using Freight for ISO 14083 reporting\
\
Understand how our Freight endpoint allows emission estimation and reporting in compliance with ISO 14083:2023](/docs/guides/understanding/freightv2-ISO14083)
[How To Report Biogenic CO2\
\
Guidance on Biogenic carbon dioxide (CO2) emissions and how to report them using Climatiq.](/docs/guides/understanding/biogenic_co2)
[How To Use Fuel activity\_id\
\
Understand fuel `activity_id`s and how to find the right fuel emission factor for your estimation.](/docs/guides/understanding/fuel_activity_id)
[Quickstart](/docs/guides/tutorials/quickstart "Quickstart")
---
# Getting Started - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Getting Started
Getting Started
===============
The Climatiq API is designed to help developers build tools to automate calculation of the environmental impact of any business or organization's activity.
The API is organized around REST. It has predictable resource-oriented URLs; accepts JSON-encoded request bodies; returns JSON-encoded responses; and uses standard HTTP response codes, authentication, and verbs. To help maintain security, all requests must be made over HTTPS. Calls made over plain HTTP will fail.
Base URL[](#base-url)
----------------------
https://api.climatiq.io
Authentication[](#authentication)
----------------------------------
Every operation on our REST API requires authentication using an API key. Detailed information can be found on our [Authentication page](/docs/api-reference/authentication)
.
Errors[](#errors)
------------------
The Climatiq API uses conventional HTTP response codes to indicate the success or failure of an API request, such as `200` for "OK", and `400` for "Bad Request". The full list of status codes used, and errors returned can be found [here](/docs/api-reference/errors)
.
Compression[](#compression)
----------------------------
To enable compression, define an `Accept-Encoding` header with the value `gzip` for gzip compression or `br` for brotli compression.
Accept-Encoding: gzip
[Authentication](/docs/api-reference/authentication "Authentication")
---
# Quickstart - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Quickstart
Quickstart
==========
**This guide will walk you through making your first estimation with the Climatiq API using a real-life example.**
Prerequisites[](#prerequisites)
--------------------------------
* Sign up for Climatiq and have [your API key ready](/docs/guides/how-tos/getting-api-key)
.
* Familiarity with [curl (opens in a new tab)](https://curl.se/)
or other ways of interacting with HTTP APIs. If you're not familiar with curl you might want to check out [this tutorial (opens in a new tab)](https://www.digitalocean.com/community/tutorials/workflow-downloading-files-curl)
.
Introduction to Emission Factors[](#introduction-to-emission-factors)
----------------------------------------------------------------------
Climatiq API estimates **how much greenhouse gases your activities emit** using validated conversion factors known as _emission factors_. An emission factor is a way to convert different human activities into greenhouse gases in terms of [CO2 equivalent (opens in a new tab)](https://www.myclimate.org/information/faq/faq-detail/what-are-co2-equivalents/)
(CO2e), usually expressed in kilograms. Climatiq can answer questions like:
1. How much CO2e is emitted taking the train from Paris to Berlin?
2. How much CO2e is emitted spending $1,000 on soft drinks in the US?
3. How much CO2e is emitted staying a night at a hotel in China?
Your First Estimate[](#your-first-estimate)
--------------------------------------------
Let's estimate the greenhouse gas emissions of an average UK household based on electricity consumption (4,200 kWh per year) using the emission factor for the activity `electricity-energy_source_grid_mix`. This factor represents the _average_ emission for the electricity grid.
### Request[](#request)
Use [curl (opens in a new tab)](https://curl.se/)
to make an API call:
* Replace `$CLIMATIQ_API_KEY` with your API key and run the command in your terminal.
* The API endpoint that's used to estimate how carbon intensive an activity is, is located at: `https://api.climatiq.io/data/v1/estimate`
An API call to this endpoint looks like the block below.
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": 4200, "energy_unit": "kWh" } }'
In this example, we provide the `parameters` argument for the calculations and they indicate that we'd like it to calculate the emissions for 4.200 kWh.
### Response[](#response)
You should get a response from the API back that looks like this:
{ "co2e": 3402, "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": 3402, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 4200, "activity_unit": "kWh" }, "audit_trail": "selector"}
The API returns quite a few values but the most relevant values are `co2e` and `co2e_unit`, which together describe how much CO2e is emitted by the given activity. In this case, **yearly energy consumption emits approximately 4381 kg of CO2e**.
([Check out this table](/docs/api-reference/estimate#response)
to see a description of every attribute in the response)
If you've made it this far you've made your first API call and seen the results in your terminal!
Next Steps[](#next-steps)
--------------------------
* Explore more emission factors in the [Climatiq Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
.
* Dive into the [API docs](/docs/api-reference)
or in-depth knowledge on using the API.
[Overview](/docs/guides "Overview")
[Upload and Use Private Emission Factors](/docs/guides/tutorials/private-emission-factors "Upload and Use Private Emission Factors")
---
# Estimation - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Basic Estimate
Estimation
==========
Estimation operations are performed to calculate emissions produced by one or more activities, based on multiplying activity data by the appropriate emission factors.
Estimate[](#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](/docs/api-reference/search)
inside the `unit_type` attribute. See [all available emission factors in our Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
.
### Request[](#request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* emission\_factorrequired [Selector](/docs/api-reference/models/selector)
Emission factor ID or selection parameters selector.
* parametersrequired [Parameters](/docs/api-reference/models/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[](#response)
This endpoint returns an [Estimation](/docs/api-reference/models/estimation#estimation)
, which includes the total amount of emissions in `kgCO2e` and the emission factor used to calculate the emissions.
Response parameters
* Estimation[Estimation](/docs/api-reference/models/estimation#estimation)
_object_
An Estimation that describes the total amount of co2e and the emission factor used.
{ "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"}
### Batch Estimate Endpoint[](#batch-estimate-endpoint)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
[Classifications v2 (preview 1)](/docs/api-reference/classifications/classifications-v2-preview1 "Classifications v2 (preview 1)")
[Cloud Computing](/docs/api-reference/computing "Cloud Computing")
---
# Search - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Search
Search
======
GET Allows you to determine what emission factors are available to be used in your estimates.
You can search for free-text queries with the `query` parameter, or filter by parameters such as `category`, `source`, `region`, `year` `calculation_method`, `source_lca_activity` or `id`.
If you are using the `query` parameter, the results will be returned in order of how well they match your free-text query.
This endpoint is paginated, and will return `current_page` and `last_page` so you can determine which page you are on. You switch pages by using the `page` query parameter.
https://api.climatiq.io/data/v1/search
Request[](#request)
--------------------
Request parametersShould be sent as an URL-encoded query string
* data\_versionrequired string
The required [Data Version](/docs/api-reference/data-version-endpoint)
string for this request.
* querystring
A free-text query that will match ids, names, descriptions, etc. of emission factors. This uses fuzzy matching, so your query does not need to be precise. Spaces need to be encoded as `+` or `%20`
* activity\_idstring
Filter by the id of a specific activity. Multiple emission factors might share the same activity. You may specify an asterisk (`*`) at the end of the activity id to act as a wildcard character, matching any ids that begin with the string before the asterisk.
* idstring
Filter by the id of a specific emission factor. As IDs are unique, this will only ever return a maximum of 1 emission factor. If using `id`, the emission factor will only be returned if it was not added later than the provided data version.
* categorystring
Filters by emission factor category
* sectorstring
Filters by emission factor sector
* sourcestring
Filters emission factors by data source
* source\_datasetstring
Filters emission factors by a given dataset from a source
* yearinteger
Filters emission factors by the year in which the emission factor is considered most relevant, according to the source.
* regionstring
Filters emission factors by geographic region to which it applies. You may specify an asterisk (`*`) at the end of the region to act as a wildcard character, matching any regions, such as sub-regions, that begin with the string before the asterisk.
* unit\_typestring
Filters emission factors by what unit (such as money, energy or volume) the factor accepts.
* source\_lca\_activitystring
The [Life Cycle Assessment (LCA)](/docs/guides/tutorials/lca)
activity with which this factor is associated.
* calculation\_methodstring
The calculation method that is used to calculate the emission factor. Can be either `ar4`, `ar5` or `ar6`. Not providing a value means that this defaults to the latest calculation methodology the source supports. [Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation)
* allowed\_data\_quality\_flagsarray of strings
Default value: [View defaults](/docs/guides/understanding/data-quality#data-quality-flags)
A list of data quality flags that you are willing to allow for this query. You can provide a comma-separated list of data quality flags you want to allow, or the value `none` if you only want emission factors without detected data quality issues. See the guide on [data quality flags](/docs/guides/understanding/data-quality)
for more information.
Default Value
[View defaults](/docs/guides/understanding/data-quality#data-quality-flags)
* access\_typestring
Filters by the access type of the emission factors. Allowed values are `public`, `private` and `premium`
* pageinteger
Default value: 1
Which page of results to retrieve.
Default Value
1
* results\_per\_pageinteger
Default value: 20
How many results to return per page. Max is 500.
Default Value
20
curl --request GET \ --url 'https://api.climatiq.io/data/v1/search?query=light+duty+trucks&data_version=^6&year=2021&results_per_page=1' \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
Response[](#response)
----------------------
The response includes a paginated list of emission factors filtered by the request parameters above.
Response parameters
* resultsarray
A list of emission factors for this page.
✖ Hide child attributes
* * *
results\[x\].idstring
The unique ID describing this particular emission factor.
* * *
results\[x\].activity\_idstring
The ID describing the activity that this emission factor applies to. Multiple emission factors can share the same `activity_id`, e.g. if they are from a different source or apply to a different region.
* * *
results\[x\].access\_typestring
Whether or not the data is publicly available or private to your project. Can be either `private` or `public`. Public emission factors are available to all, while private emission factors are only accessible to you.
* * *
results\[x\].namestring
Emission factor name.
* * *
results\[x\].categorystring
Emission factor category.
* * *
results\[x\].sectorstring
Emission factor sector.
* * *
results\[x\].sourcestring
Emission factor publisher.
* * *
results\[x\].source\_linkstring
Link to emission factor publisher.
* * *
results\[x\].uncertainty_number or null_
Emission factor uncertainty factor (%).
* * *
results\[x\].yearnumber
The year in which the emission factor is considered most relevant, according to the source.
* * *
results\[x\].year\_releasednumber
The year in which the emission factor was released by the source.
* * *
results\[x\].regionstring
A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor applies.
* * *
results\[x\].region\_namestring
Geographic region to which the emission factor applies (in English).
* * *
results\[x\].descriptionstring
Emission factor description.
* * *
results\[x\].unitstring
The unit in which the `factor` field is expressed.
* * *
results\[x\].unit\_typestring
The [Unit types](/docs/api-reference/unit-types)
that this emission factor accepts.
* * *
results\[x\].source\_lca\_activitystring
Which LCA activity the emission factor corresponds to. [Read more about life cycle assessments here.](/docs/guides/tutorials/lca)
* * *
results\[x\].supported\_calculation\_methodsarray of _strings_
The methods of CO2e calculation supported for this emission factor.
* * *
results\[x\].factornumber or null
CO2e emission factor value, expressed in kgCO2e emitted per unit of activity provided in the `unit` field. This is available as add-on. Reach out to our team to know more. Otherwise the value is `null` for the community plan. You can use the [estimate endpoint](/docs/api-reference/estimate)
to calculate the emissions generated by specifying this `factor`.
* * *
results\[x\].factor\_calculation\_method`"ar4"`, `"ar5"`, `"ar6"` or `null`
Indicates which conversion values were used (IPCC 4th, 5th or 6th Assessment Report) to generate the returned CO2e emission factor. If `factor` is `null`, this is also `null`.
* * *
results\[x\].factor\_calculation\_origin`"climatiq"`, `"source"` or `null`
Indicates whether the CO2e emission factor provided in this response was provided by the source or calculated by Climatiq. If `factor` is `null`, this is also `null`.
* * *
results\[x\].constituent\_gases_[constituent gases](/docs/api-reference/search#constituent-gases)
_
Indicates which gases the CO2e emission factor is composed of.
* * *
results\[x\].data\_version[data version information](/docs/api-reference/search#data-version-information)
Gives relevant [data version information](/docs/guides/understanding/data-versioning)
about this emission factor, such as if it has a newer version available, or has been deprecated.
* * *
results\[x\].data\_version\_informationobject
This field is deprecated and should not be used. Refer to the `data_version` field instead.
* current\_pagenumber
The current page you have retrieved.
* last\_pagenumber
The last page that there are results for.
* total\_resultsnumber
How many results there are in total across all pages.
* possible\_filtersobject
A list of potential filters you can use to further narrow down your query. [_See below._](/docs/api-reference/search#possible_filters)
{ "current_page": 1, "last_page": 3, "total_results": 3, "results": [ { "activity_id": "commercial_vehicle-vehicle_type_truck_light-fuel_source_na-engine_size_na-vehicle_age_na-vehicle_weight_na", "id": "05d034db-dfe7-462e-9a19-a69ecd65a114", "name": "Light-Duty Truck", "category": "Vehicles", "sector": "Transport", "source": "EPA", "source_link": "https://www.epa.gov/climateleadership/ghg-emission-factors-hub", "source_dataset": "GHG Emission Factors Hub", "uncertainty": null, "year": 2021, "year_released": 2021, "region": "US", "region_name": "United States of America (the)", "description": "Emission intensity of light duty truck (includes full-size pickup trucks/full-size vans/extended-length SUVs with wheelbase greater than 121 inches). Retrieved from the EPA's GHG Emission Factors Hub (xlsx).", "unit_type": "Distance", "unit": "kg/mile", "source_lca_activity": "use_phase", "data_quality_flags": [], "access_type": "public", "supported_calculation_methods": [ "ar4", "ar5", "ar6" ], "factor": 0.4671, "factor_calculation_method": "ar6", "factor_calculation_origin": "climatiq", "constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 0.464, "ch4": 0.000012, "n2o": 0.00001 }, "data_version": { "status": "up_to_date" }, "data_version_information": { "status": "up_to_date" } } ], "possible_filters": { "year": [ 2021 ], "source": [ { "source": "EPA", "datasets": [ "GHG Emission Factors Hub" ] }, { "source": "GHG Protocol", "datasets": [ "GHG Emissions Calculation Tool" ] } ], "region": [ { "id": "US", "name": "United States of America (the)" } ], "category": [ "Fuel", "Vehicles" ], "sector": [ "Energy", "Transport" ], "unit_type": [ "Distance", "Volume" ], "source_lca_activity": [ "fuel_combustion", "use_phase" ], "access_type": [ "public" ], "data_quality_flags": [ "notable_methodological_variance" ] }}
### `possible_filters`[](#possible_filters)
The field `possible_filters` includes aggregated metadata about the results of your search request, to help you to choose further filters which would narrow down your results.
Most of the fields (`year`, `category`, `sector`, `unit_type`, `source_lca_activity`, `access_type`) contain a list enumerating each of the values present for the given field in the response. The values can be used verbatim in those fields of the search request to narrow down the results. If there is only one value, all results have the same value for this field.
The values of `region` contain a JSON object, the `id` field is a [region code](/docs/api-reference/regions#region-code)
that describes the different regions emission factors can apply to and can be used as the value for further filtering, the `name` is provided for the convenience of interactive apps to show the full name of the country.
The `source` contain a JSON object, the `source` field inside it is the source name, corresponding to the `source` for an emission factor. The `datasets` field is what datasets that belong to this particular source, is a valid `source_dataset` filter for this query.
`data_quality_flags` is named differently from its search request parameter equivalent `allowed_data_quality_flags` as it can't be used in the same way as the other filters.
* Each emission factor can have multiple, or (usually) no data quality flags, so each of your results may have the same 2 flags, then if you select only one of them you would have no more results.
* When a search doesn't specify an `allowed_data_quality_flags` list, we allow some flags by default. See [here for more information about data quality](/docs/guides/understanding/data-quality)
. Also see the documentation for the search request above for how to use `allowed_data_quality_flags` while searching.
If you're curious about how to use `possible_filters` to narrow down your searches, the [search refinement how-to](/docs/guides/how-tos/search-refinement)
has you covered.
### Constituent Gases[](#constituent-gases)
The constituent gases model explains which constituent gases the source of the data considers to be part of their calculations. These values might be null for one of several reasons:
* The source does not provide data at the constituent gas level.
* The source is a premium dataset, and part of the commercial terms dictate we cannot reveal this number.
* You do not have a commercial agreement with Climatiq to view this data.
The constituent gases also depend on the calculation methodology chosen, displayed as `factor_calculation_method` in the search results. If you filter on different calculation methodologies, you might see different constituent gas values. [Learn more about calculation methods and constituent gases here](/docs/guides/understanding/co2e-calculation)
| Attribute |
| --- |
| **co2e\_total** _number or null_
The total amount of GHG emitted per unit of activity expressed as kgCO2e, as reported by the source. It is null for Climatiq-performed calculations. |
| **co2e\_other** _number or null_
The total amount of GHG emitted that are not CO2, CH4 or N20 - expressed in kgCO2e emitted per unit of activity, as reported by the source. |
| **co2** _number or null_
The amount of carbon dioxide (CO2) emitted per unit of activity expressed as kgCO2, as reported by the source. |
| **ch4** _number or null_
The amount of methane (CH4) emitted per unit of activity expressed as kgCH4, as reported by the source. |
| **n2o** _number or null_
The amount of nitrous oxide (N2O) emitted per unit of activity expressed as kgN2O, as reported by the source. |
### Data Version Information[](#data-version-information)
The `data_version` object explains whether this emission factor has been modified in a later [data version](/docs/guides/understanding/data-versioning)
. The object contains a `status` field that contains one of three string values:
* `up_to_date`: This is the latest version of this emission factor. If this is the case, the `data_version` object will not contain any additional information.
* `replaced`: There is a more recent emission factor available. Note that if an emission factor has been replaced multiple times this will give information about the _next_ emission factor in the chain, not the most current one. The following fields are also available:
* `replaced_in` will provide the data release where this emission factor has been replaced.
* `replaced_by` will provide the ID of the newer version of the emission factor that replaced it time throughout data versions, this will give information about the _next_ emission factor in the chain, not the most current one.
* `removed`: This emission factor has been removed in a newer data release, without being replaced by something else. The following field is also available:
* `removed_in` will list the data release where this emission factor was removed.
[Errors](/docs/api-reference/errors "Errors")
[Unit Types](/docs/api-reference/unit-types "Unit Types")
---
# Authentication - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Authentication
Authentication
==============
Authenticate the app using API keys as bearer tokens. Always provide the `Authorization` header containing your API key as bearer token:
Authorization: Bearer CLIMATIQ_API_KEY
Replacing `CLIMATIQ_API_KEY` with your Climatiq API key.
**Note**: Your API keys carry many privileges, so be sure to keep them secure. Do not share your API keys in publicly accessible areas such as GitHub or through client-side code. When possible, encrypt API keys when you store them.
[Click here to sign up for API Keys (opens in a new tab)](https://app.climatiq.io/api/signup)
Having trouble? Find out how to get API keys [here](/docs/guides/how-tos/getting-api-key)
or follow our quickstart guide [here](/docs/guides/tutorials/quickstart)
.
[Getting Started](/docs/api-reference "Getting Started")
[Models](/docs/api-reference/models "Models")
---
# Intermodal Freight v2 - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Freight v2
Intermodal Freight v2 ADD-ONADD-ON
==================================
Climatiq allows you to use emission factors from the [Global Logistics Emissions Council(GLEC) (opens in a new tab)](https://www.smartfreightcentre.org/en/how-to-implement-items/what-is-glec-framework/58/)
to calculate the carbon emissions for shipping freight around the world using multiple modes of transport such as by sea, air, road or rail.
⚠️
**Read the guide or changelog first**
This is the API reference for the intermodal freight feature.
If you're just getting started, we highly recommend that you start with [the guide](/docs/guides/tutorials/intermodal)
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](/docs/changelogs/api-release/freight-v2)
which highlights which sections of this document to concentrate on.
Estimate[](#estimate)
----------------------
POST Calculate total estimated emissions produced by shipping an amount of cargo by the specified route.
https://api.climatiq.io/freight/v2/intermodal
### Request[](#request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* cargorequired object
The details of the cargo being shipped
➕ Show child attributes
* routerequired array of [Route Legs](/docs/api-reference/intermodal-freight#route-leg)
or [Locations](/docs/api-reference/intermodal-freight#location)
An array of route parts that compose the route this cargo is taking. A route must start and end with a location, and have legs between each location. Sometimes you may omit some locations and rely on [automatic routing](/docs/guides/tutorials/intermodal#automatic-routing)
.
curl --request POST \--url https://api.climatiq.io/freight/v2/intermodal \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "route": [ { "location": { "query": "Hamburg" } }, { "transport_mode": "road", "leg_details": { "rest_of_world": { "vehicle_type": "van", "vehicle_weight": "lte_3.5t", "fuel_source": "petrol" }, "north_america": { "vehicle_type": "moving" } } }, { "location": { "query": "Berlin" } } ], "cargo": { "weight": 10, "weight_unit": "t" }}'
### Response[](#response)
A response consists of the following attributes.
Response parameters
* co2efloat
The total carbon dioxide equivalent emitted for the entire trip. This encompasses logistics hubs, vehicle operations and vehicle energy provisioning.
* hub\_equipment\_co2efloat
The carbon dioxide equivalent emitted for the operation of logistics hubs during the trip. This encompasses both operational and energy provisioning emissions. Logistics hubs emissions cover the transportation and movement of cargo from one mode of transportation to another, such as moving containers from a truck to a ship.
* vehicle\_operation\_co2efloat
The carbon dioxide equivalent emitted for the part of the trip where the vehicle is being operated, such as the combustion of fuel, leakage of refrigerants etc.
* vehicle\_energy\_provision\_co2efloat
The carbon dioxide equivalent emitted for the provisioning of energy for the vehicle operations. This covers among others: electricity generation, electricity transmission and distribution losses, the production of fuel, and the transportation of fuel to the vehicle.
* co2e\_calculation\_methodstring
Which calculation methodology that was used for the calculation. The value of this is either `"ipcc_ar4_gwp100"`, `"ipcc_ar5_gwp100"`, `"ipcc_ar6_gwp100"` or `"ipcc_mixed_gwp100"`. [Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation)
* co2e\_unitstring
The unit in which the CO2e field is expressed. The value of this is always `kg`
* distance\_kmfloat
The distance in kilometers that the cargo has been shipped along the specified route.
* cargo\_tonnesfloat
The weight in tonnes which is being shipped along the specified route.
* routearray of [ResponseLocations](/docs/api-reference/intermodal-freight#responselocation)
or [ResponseLegs](/docs/api-reference/intermodal-freight#responseleg)
An array that specifies the route the cargo took. This array will always consist of alternating response locations and response legs. It will always start and end with a location. Even if you have omitted any locations, they will not be omitted in the response.
{ "co2e": 2781, "hub_equipment_co2e": 12, "vehicle_operation_co2e": 2099, "vehicle_energy_provision_co2e": 671, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "cargo_tonnes": 10, "distance_km": 285.5, "route": [ { "type": "location", "co2e": 6, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Freight logistics - transshipment - ambient", "source": "GLEC", "source_dataset": "Default fuel efficiency and GHG emission intensity values v3.0", "year": "2023", "region": "GLOBAL", "region_name": "Global" } ], "name": "Hamburg, Germany", "latitude": 53.55562, "longitude": 9.98745, "confidence_score": 1 }, { "type": "leg", "co2e": 2769, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Van <3.5t - Petrol", "source": "GLEC", "source_dataset": "Default fuel efficiency and GHG emission intensity values v3.0", "year": "2023", "region": "EU_S_AMERICA", "region_name": "Europe and South America" } ], "vehicle_operation_co2e": 2099, "vehicle_energy_provision_co2e": 671, "transport_mode": "road", "distance_km": 285.5, "notices": [] }, { "type": "location", "co2e": 6, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Freight logistics - transshipment - ambient", "source": "GLEC", "source_dataset": "Default fuel efficiency and GHG emission intensity values v3.0", "year": "2023", "region": "GLOBAL", "region_name": "Global" } ], "name": "Berlin, Germany", "latitude": 52.51604, "longitude": 13.37691, "confidence_score": 1 } ]}
**OpenStreetMap attribution**
Climatiq draws information from many sources, including [OpenStreetMap (opens in a new tab)](https://www.openstreetmap.org)
. The license of that information requires you to provide attribution where this information comes from. If you display information such as routes and location names externally, you should make sure you correctly attribute this data to OpenStreetMaps, e.g. by writing "May contain information from OpenStreetMap".
Route Leg[](#route-leg)
------------------------
Each route in the request has one or more legs. A leg is a transition between two locations. A leg contains the following properties.
* transport\_moderequired string
How the goods are transported. Allowed values are `air`, `sea`, `road`, `rail`.
* leg\_detailsobject
The details of the leg such as fuel and vessel type. Valid values here vary between `transport_mode`. Allowed values are [RoadDetails](/docs/api-reference/intermodal-freight#road)
, [SeaDetails](/docs/api-reference/intermodal-freight#sea)
, [AirDetails](/docs/api-reference/intermodal-freight#air)
or [RailDetails](/docs/api-reference/intermodal-freight#rail)
.
* planned\_distance\_kmfloat
Planned Distance or [Shortest Feasible Distance](/docs/guides/understanding/freightv2-ISO14083#shortest-feasible-distance)
for the leg. We will use this distance instead of the planned distance we would normally calculate. If you need to use an actual distance, be careful to apply a Distance Adjustment Factor (DAF) in order to reduce the distance. For example, GLEC suggests that for sea transport, a DAF of 15% can be used to account for average container sea transport distances being on average 15% longer than the shortest feasible distance - ie. divide the actual distance by 1.15 to get the appropriate planned distance. GLEC does not provide guidance for any other transport modes.
**A route cannot by default have more than three legs. If you need more than three legs, you can call the API endpoint multiple times, or [contact Climatiq (opens in a new tab)](https://www.climatiq.io/contact-us)
to get this limit raised**
### Road[](#road)
A leg with the `"transport_mode": "road"` can include more specific journey details through the `leg_details` object.
As GLEC uses different methodologies for North America and the rest of the world, the parameters you can provide are different for these two regions. The API allows you to provide parameters for both regions, and the API will only use the relevant one, depending on the actual trip taken.
* rest\_of\_worldobject
Default value: See [here](/docs/api-reference/intermodal-freight#road-outside-of-north-america)
Details used for trips outside of North America. These parameters can always be provided, but will only apply to road legs outside of North America. Use [this object](/docs/api-reference/intermodal-freight#road-outside-of-north-america)
for combustion vehicles or [this object](/docs/api-reference/intermodal-freight#road-electric-vehicles)
for electric vehicles.
Default Value
See [here](/docs/api-reference/intermodal-freight#road-outside-of-north-america)
* north\_americaobject
Default value: See [here](/docs/api-reference/intermodal-freight#road-combustion-vehicles-within-north-america)
Details used for trips within North America. These parameters can always be provided, but will only apply to road legs within North America. Use [this object](/docs/api-reference/intermodal-freight#road-combustion-vehicles-within-north-america)
for combustion vehicles or [this object](/docs/api-reference/intermodal-freight#road-electric-vehicles)
for electric vehicles.
Default Value
See [here](/docs/api-reference/intermodal-freight#road-combustion-vehicles-within-north-america)
#### Road (Outside of North America)[](#road-outside-of-north-america)
A leg with the `"transport_mode": "road"`, that is taking place outside of North America can specify further details about the journey by including this object under `leg_details.rest_of_world`.
**These options do not apply to trips with combustion vehicles within North America, where the input options are more limited. If your trip is in North America, see the section below on [combustion vehicles for North America.](/docs/api-reference/intermodal-freight#road-combustion-vehicles-within-north-america)
or the section on [electric vehicles](/docs/api-reference/intermodal-freight#road-electric-vehicles)
which work for both regions.**
Different `vehicle_type`s have different requirements and options. Please consult the table further down for the list of valid parameter combinations.
* vehicle\_typerequired string
Default value: `articulated_truck`
The type of vehicle that is used for the transportation. `articulated` and `rigid` refers to [truck types](https://www.nti.com.au/better-business-hub/blog/do-you-know-your-truck-types)
. All valid values are: `van`, `rigid_truck`, `articulated_truck`, `articulated_truck_incl_lightweight_trailer`
Default Value
`articulated_truck`
* vehicle\_weightrequired string
Default value: `lte_34t`
The carrying capacity of the vehicle, as a string specifying the range. E.g. `gt_60t_lte_72t`means a carrying capacity greater than 60tons and less than or equal to 72tons. Refer to the table below for all valid combinations of values.
Default Value
`lte_34t`
* fuel\_sourcerequired string
Default value: `diesel`
The fuel source that the vehicle is running on. Valid values vary depending on the vehicle type, but all valid values are: `diesel`, `cng`, `lng`, `bio_lng`, `bio_lng_or_diesel`, `cng_or_diesel`,`lng_or_diesel`, `petrol`, `electricity`
Default Value
`diesel`
* load\_typestring
Default value: Average
The type of load the vehicle carries. Valid values vary depending on the vehicle type, but all valid values are: `light`, `heavy`, `container`.
Default Value
Average
##### Valid parameter combinations (Outside of North America)[](#valid-parameter-combinations-outside-of-north-america)
Please consult this table to see what valid combinations of values are when outside of north america, this includes electrical vehicles:
| `vehicle_type` Parameter | `fuel_source` Parameter | `vehicle_weight` Parameter | `load_type` Parameter |
| --- | --- | --- | --- |
| `articulated_truck` | `lng`, `lng_or_diesel`, `bio_lng`, `bio_lng_or_diesel`, `cng`, `cng_or_diesel` | `lte_40t` | `container`, `null` |
| | `diesel` | `lte_34t`, `gt_34t_lte_40t` | `container`, `null` |
| | | `gt_40t_lte_44t` | `container`, `heavy`, `light`, `null` |
| | | `gt_44t_lte_60t` | `container`, `heavy`, null\` |
| | | `gt_60t_lte_72t` | `container`, `heavy` |
| `articulated_truck_incl_lightweight_trailer` | `diesel` | `lte_40t` | `heavy` |
| `rigid_truck` | `cng` | `gt_3.5t_lte_7.5t`, `gt_7.5t_lte_12t`, `gt_12t_lte_20t`, `gt_20t_lte_26t` | `null` |
| | `diesel` | `gt_3.5t_lte_7.5t`, `gt_7.5t_lte_12t`, `gt_12t_lte_20t`, `gt_20t_lte_26t` | `null` |
| | | `gt_26t_lte_32t` | `container`, `null` |
| | `lng` | `gt_20t_lte_26t` | `null` |
| | `electricity` | `gt_3.5t_lte_7.5t`, `gt_7.5t_lte_12t`, `gt_12t_lte_20t` `gt_26t_lte_40t` | `light`, `null` |
| `van` | `diesel`, `petrol`, `cng`, `lpg`, `electricity` | `lte_3.5t` | `null` |
#### Road (Combustion vehicles within North America)[](#road-combustion-vehicles-within-north-america)
A leg with the `"transport_mode": "road"`, taking place inside North America and using a combustion vehicle can specify further details about the journey by including this object under `leg_details.north_america`.
**These options only apply to trips with combustion vehicles within North America. If your trip is outside of North America, see the section above on [vehicles outside of North America.](/docs/api-reference/intermodal-freight#road-outside-of-north-america)
or, if the trip is using an electric vehicle, see the section on [electric vehicles](/docs/api-reference/intermodal-freight#road-electric-vehicles)
which works for both regions.**
* vehicle\_typerequired string
Default value: `general`
The type of vehicle that is used for the transportation. All valid values are: `auto_carrier`, `dray`, `expedited`, `flatbed`, `general`, `heavy_bulk`, `ltl_or_dry_van`, `mixed`, `moving`, `package`, `refrigerated`, `specialized`, `tanker`, `tl_or_dry_van`, `van`
Default Value
`general`
#### Road (Electric Vehicles)[](#road-electric-vehicles)
A leg with the `"transport_mode": "road"`, with an electric car can specify further details about the journey by including this object under either `leg_details.north_america` or `leg_details.rest_of_world`. If the `fuel_source` is `electricity`, the vehicle is considered an electric vehicle.
**These options are valid globally (both inside and outside of North America), but only apply to electric vehicles. If your transportation uses combustion engine, see the above sections.**
Different `vehicle_type`s have different requirements and options. Please consult the table further down for the list of valid parameter combinations.
* fuel\_sourcerequired string
Must be `electricity` for electric vehicles.
* vehicle\_typerequired string
The type of vehicle that is used for the transportation. All valid values are: `van`, `rigid_truck`
* vehicle\_weightrequired string
The carrying capacity of the vehicle, as a string specifying the range. E.g. `gt_34t_lte_40t`means a carrying capacity greater than 34tonnes and less than or equal to 40tonnes. Refer to the table below for all valid combinations of values.
* load\_typestring
Default value: Average
The type of load the vehicle carries. Valid values vary depending on the vehicle type, but all valid values are: `light`
Default Value
Average
##### Valid parameter combinations (Electric only)[](#valid-parameter-combinations-electric-only)
Please consult this table to see what valid combinations of values are then using Electric trucks worldwide:
| `fuel_source` Parameter | `vehicle_type` Parameter | `vehicle_weight` Parameter | `load_type` Parameter |
| --- | --- | --- | --- |
| `electricity` | `rigid_truck` | `gt_3.5t_lte_7.5t`, `gt_7.5t_lte_12t`, `gt_12t_lte_20t` `gt_26t_lte_40t` | `light`, `null` |
| `electricity` | `van` | `lte_3.5t` | `null` |
### Sea[](#sea)
A leg with the `"transport_mode": "sea"`, can specify further details about the journey by including this object under `leg_details`.
* vessel\_typerequired string
Default value: `container`
The type of vessel that is used for the transportation. Refer to the table below for all valid combinations of values.
Default Value
`container`
* tonnagestring
The tonnage the ship can carry, as a string specifying the range E.g. `gte_5dwkt_lt_10dwkt` means more than (or equal to) 5 [deadweight kilotonnes](https://en.wikipedia.org/wiki/Deadweight_tonnage)
, and less than 10 deadweight kilotonnes. You might also see the abbreviation `gt` for [gross tonnage](https://en.wikipedia.org/wiki/Gross_tonnage)
. Refer to the table below for all valid combinations of values.
* fuel\_sourcestring
The type of fuel that the ship uses. Refer to the table below for all valid combinations of values.
#### Valid parameter combinations[](#valid-parameter-combinations)
Please consult this table to see what valid combinations of values are:
| `vessel_type` Parameter | `tonnage` Parameter | `fuel_source` Parameter |
| --- | --- | --- |
| `container` | `null` | `null` |
| `bulk_carrier` | `lt_10dwkt`, `gte_10dwkt_lt_35dwkt`, `gte_35dwkt_lt_60dwkt`, `gte_60dwkt_lt_100dwkt`, `gte_100dwkt_lt_200dwkt`, `gte_200dwkt` | `hfo`, `vlsfo`, `mdo` |
| `chemical_tanker` | `lt_5dwkt`, `gte_5dwkt_lt_10dwkt`, `gte_10dwkt_lt_20dwkt`, `gte_20dwkt_lt_40dwkt`, `gte_40dwkt` | `hfo`, `vlsfo`, `mdo` |
| `ferry_ropax` | `lt_2000gt`, `gte_2000gt_lt_5000gt`, `gte_5000gt_lt_10000gt`, `gte_10000gt_lt_20000gt`, `gte_20000gt` | `hfo`, `vlsfo`, `mdo` |
| `general_cargo` | `lt_5dwkt`, `gte_5dwkt_lt_10dwkt`, `gte_10dwkt_lt_20dwkt`, `gte_20dwkt` | `hfo`, `vlsfo`, `mdo` |
| `liquefied_gas_tanker` | `lt_50000cbm`, `gte_50000cbm_lt_100000cbm`, `gte_100000cbm_lt_200000cbm`, `gte_200000cbm` | `hfo`, `vlsfo`, `mdo` |
| `oil_tanker` | `lt_5dwkt`, `gte_5dwkt_lt_10dwkt`, `gte_10dwkt_lt_20dwkt`, `gte_20dwkt_lt_60dwkt`, `gte_60dwkt_lt_80dwkt`, `gte_80dwkt_lt_120dwkt`, `gte_120dwkt_lt_200dwkt`, `gte_200dwkt` | `hfo`, `vlsfo`, `mdo` |
| `other_liquids_tankers` | `lt_1dwkt`, `gte_1dwkt` | `hfo`, `vlsfo`, `mdo` |
| `refrigerated_bulk` | `lt_2dwkt`, `gte_2dwkt_lt_6dwkt`, `gte_6dwkt_lt_10dwkt`, `gte_10dwkt` | `hfo`, `vlsfo`, `mdo` |
| `ro_ro` | `lt_5dwkt`, `gte_5dwkt_lt_10dwkt`, `gte_10dwkt_lt_15dwkt`, `gte_15dwkt` | `hfo`, `vlsfo`, `mdo` |
| `vehicle` | `lt_30000gt`, `gte_30000gt_lt_50000gt`, `gte_50000gt` | `hfo`, `vlsfo`, `mdo` |
⚠️
**Roll on - Roll off (ro-ro) vessel type behavior**
The emission factors for the `ro_ro` (Roll on - Roll off) vessel type are calculated differently than other types of vessels. For `ro_ro` vessels, the weight should include both the vehicle and any cargo it carries. In contrast, for other vessel types, only the weight of the cargo should be considered.
If you're shipping cargo using a vehicle on a `ro_ro` vessel, you'll need to adjust your API request accordingly. You may also choose to attribute only a portion of the emissions to yourself if you are transporting only part of the vehicle's cargo.
Please note that the Climatiq API does not automatically select `ro_ro` vessels as the default option, so you only need to take this into account if you explicitly choose this vessel type.
### Air[](#air)
A leg with the `"transport_mode": "air"`, can specify further details about the journey by including this object under `leg_details`.
* aircraft\_typestring
Default value: Unknown
The aircraft type used to carry the shipment. Use `freighter` if it is a dedicated cargo plane, or `belly_freight` if it is transported in the belly of a passenger plane.
Default Value
Unknown
* radiative\_forcing\_indexfloat
Default value: `2`
The radiative forcing index to multiply the emissions by (see info box below). If you do not want a radiative forcing index to be applied, you may specify `1`
Default Value
`2`
**Air travel and radiative forcing**
GLEC default emission factors do not include a [Radiative Forcing Index (RFI) (opens in a new tab)](https://sustainable.stanford.edu/sites/g/files/sbiybj26701/files/media/file/s3-radiative-forcing-rfi-memo_public.pdf)
. RFIs are applied to account for the increased impact on global heating made by greenhouse gases released directly into the upper atmosphere by aircraft. RFI values depend on things like altitude and trip length and are subject to uncertainty and disagreements. To perform the most accurate calculations, this endpoint currently applies an RFI of 2 to all flights, based on the [latest available science (opens in a new tab)](https://link.springer.com/article/10.1007/s11367-018-1556-3)
. If a Radiative Forcing Index has been applied, a [notice](/docs/api-reference/intermodal-freight#notice)
will be returned.
### Rail[](#rail)
A leg with the `"transport_mode": "rail"`; you can specify further details about the journey by including this object under `leg_details`.
* fuel\_sourcestring
Default value: Regional average or default
The fuel type that the train runs on. Valid values are `diesel`, `electricity`; do not include if hybrid or unknown (an averaged factor will be applied). `electric` can only be specified for journeys within Europe or Asia.
Default Value
Regional average or default
* load\_typestring
Default value: Average
The load that the train is carrying. Valid values are `building_materials`, `cars`, `cereals`, `chemicals`, `coal_steel`, `container`, `manufactured_products`, `trailer_only_on_train`, `truck_plus_trailer_on_train`
Default Value
Average
Location[](#location)
----------------------
A trip always has two or more locations.
| Request Location Attributes | Required |
| --- | --- |
| **location** _Location_
Either a [QueryLocation](/docs/api-reference/regions#query-location)
, an [IataCodeLocation](/docs/api-reference/regions#iata-code-location)
, an [UNLocodeLocation](/docs/api-reference/regions#unlocode-location)
or a [CoordinateLocation](/docs/api-reference/regions#coordinate-location) | **required** |
| **location\_options** [_Location Options_](/docs/api-reference/intermodal-freight#location-options)
Extra options that a location can have. See section below. | _optional_ |
### Location Options[](#location-options)
There are other options that are sometimes relevant to change. If a location is adjacent to a [fixed-transition point leg](/docs/guides/tutorials/intermodal#transition-points)
, Climatiq automatically makes small corrections to turn your provided location into the proper port, airport or railway station. See [Automatic Location Correction](/docs/guides/tutorials/intermodal-v2#automatic-location-correction)
for more details.
| Location Options Attributes | Required | Default |
| --- | --- | --- |
| **override\_transition** _boolean_
If the location is known to be valid for transition between different modalities, for example when providing the coordinates of a private railway terminal or dock, this overrides our attempts to automatically correct the location to a known fixed transition point and prevents errors. | _optional_ | `false` |
| **tolerance\_km** _float_
The maximum distance, in km, that we would correct a location to match a mixed transition point. Increasing this can help with some errors which occur with very large ports, etc. for which different locations may be identified. | _optional_ | `10` |
| **logistics\_hubs\_type** _string_
The type of logistics hub operation performed at this location, if you wish to override the default. Logistics hubs are where freight is stored and processed, and where freight is moved between vehicles. Valid values are: `none`, `transshipment`, `storage_and_transshipment`, `warehouse`, `liquid_bulk_terminals` and `maritime_container_terminals`. Refrigerated variants exist for all these values, and are selected if the cargo is marked as refrigerated. | _optional_ | `transshipment` unless one of the adjacent legs is sea container shipping, then `maritime_container_terminals` |
Response Models[](#response-models)
------------------------------------
These are more in-depth explanations of the models returned by [the intermodal freight endpoint](/docs/api-reference/intermodal-freight#estimate)
.
### ResponseLocation[](#responselocation)
The location in the `route` array of the response will contain the following properties
| Response Location attributes |
| --- |
| **type** _"location"_
constant to easily show whether the item is a location or leg |
| **co2e** _float_
The carbon dioxide equivalent emitted for the operation of logistics hubs at this location. This encompasses both operational and energy provisioning emissions. Logistics hubs emissions cover the transportation and movement of cargo from one mode of transportation to another, such as moving containers from a truck to a ship. |
| **co2e\_calculation\_method** _string_ or _null_
Which calculation methodology that was used for the calculation. The value of this is either `"ipcc_ar4_gwp100"`, `"ipcc_ar5_gwp100"`, `"ipcc_ar6_gwp100"`, `"ipcc_mixed_gwp100"` or `null` (if the request specified that no transshipment should be estimated).
[Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation) |
| **co2e\_unit** _string_
The unit in which the CO2e fields is expressed. The value of this is always `kg` |
| **name** _string_
A human-readable name of the location |
| **latitude** _string_ or _null_
The latitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled. |
| **longitude** _string_ or _null_
The longitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled. |
| **confidence\_score** _float_
A confidence score between 0 and 1, determining how certain we are that the location matches your query. Only exists if the input location was a `QueryLocation` |
| **source\_trail** _array of [SourceDataPoint](/docs/api-reference/source-trail#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](/docs/api-reference/source-trail)
. |
### ResponseLeg[](#responseleg)
The leg in the `route` array of the response will contain the following properties
| Response Leg attributes |
| --- |
| **type** _"leg"_
constant to easily show whether the item is a location or leg |
| **co2e** _float_
The total carbon dioxide equivalent emitted for this leg of the trip. This encompasses both vehicle operations and vehicle energy provisioning. |
| **co2e\_calculation\_method** _string_
Which calculation methodology that was used for the calculation. The value of this is either `ipcc_ar4_gwp100`, `ipcc_ar5_gwp100`, `ipcc_ar6_gwp100` or `ipcc_mixed_gwp100`.
[Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation) |
| **co2e\_unit** _string_
The unit in which the CO2e fields is expressed. The value of this is always `kg` |
| **vehicle\_operation\_co2e** _float_
The carbon dioxide equivalent emitted for the part of the trip where the vehicle is being operated, such as the combustion of fuel, leakage of refrigerants etc. |
| **vehicle\_energy\_provision\_co2e** _float_
The carbon dioxide equivalent emitted for the provisioning of energy for the vehicle operations. This covers among others: electricity generation, electricity transmission and distribution losses, the production of fuel, and the transportation of fuel to the vehicle. |
| **transport\_mode** _string_
What transport mode this leg corresponds to. Will be `"road"`, `"air"`, `"sea"` or `"rail"` |
| **distance\_km** _float_
The distance in kilometers for this leg of the trip. |
| **source\_trail** _array of [SourceDataPoint](/docs/api-reference/source-trail#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](/docs/api-reference/source-trail)
. |
| **notices** _array of [Notice](/docs/api-reference/intermodal-freight#notice)
_
An array of notices for this leg, that is relevant for understanding the result. This could be if Climatiq cannot accurately calculate the distance for a certain route, but still performed a less-accurate calculation. |
### Notice[](#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 value | description |
| --- | --- |
| `great_circle_distance_used` | Great Circle Distance was used for the leg in absence of more detailed routing capability. |
| `partial_great_circle_distance_used` | We were not able to route the entire leg successfully. Parts of the leg was filled with great circle distance calculations. |
| `truck_ferry_used` | The truck used for the journey was put on a ferry for part of the journey, sea factors were used for the covered distance |
| `truck_rail_used` | The truck used for the journey was put on a train for part of the journey, rail factors were used for the covered distance |
| `region_fallback` | Factors or calculation methods for the exact region are not available, we have used a fallback region which we believe best covers the specified region |
| `radiative_forcing_applied` | An adjustment was applied to the co2e of the estimate, due to the effects of radiative forcing. |
| `global_electricity_factor_used` | A country-specific electricity factor wasn't available, so global was used instead. |
[Management (preview)](/docs/api-reference/management "Management (preview)")
[Freight v1](/docs/api-reference/intermodal-freight/intermodal-freight-v1 "Freight v1")
---
# How to calculate the carbon emission of your cloud services - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Calculate Cloud Carbon Footprint
How to calculate the carbon emission of your cloud services
===========================================================
**Understanding and calculating the carbon footprint of your cloud services has never been simpler. This tutorial will walk you through using Climatiq API to assess emissions based on a variety of cloud computing factors.**
⚠️
**Subscription plan required**
This is a paid feature. Please see our [pricing page](https://www.climatiq.io/pricing)
for more details.
Key Considerations in Cloud Carbon Emissions[](#key-considerations-in-cloud-carbon-emissions)
----------------------------------------------------------------------------------------------
Cloud computing power utilization depends on several factors:
* The CPU, Memory, and Storage demand of your services
* How well utilized the machines in the data centers are used.
* Efficiency in data centers regarding cooling and electricity usage, usually denoted as [Power Usage Effectiveness (opens in a new tab)](https://en.wikipedia.org/wiki/Power_usage_effectiveness)
or PUE.
* Where the data centers are located to determine the electricity grid mix.
* The embodied emissions, meaning the emissions related to the manufacturing and disposal of the physical components.
With these factors in mind, let's explore different types of services and how Climatiq can help you calculating your emissions.
Carbon Emissions for Virtual Machines[](#carbon-emissions-for-virtual-machines)
--------------------------------------------------------------------------------
Several services let you rent a Virtual Machine (VM) in the cloud, such as GCP's Compute Engine, Azure Virtual Machines, or AWS's EC2 instances. Other services might also be backed by a VM that you designate, like Azure's App Service or Kubernetes clusters.
For all instances where your workload runs on a specific VM, Climatiq provides a [Virtual Machine Endpoint](/docs/api-reference/computing#vm-instance)
where you need to put in the region you're running, instance type, and optionally, the CPU load of the instance. This will automatically compute the electricity used for memory and CPU usage, and embodied emissions for the specified instance type.
### Virtual Machines Example[](#virtual-machines-example)
Here is an example of renting a `t2.nano` from AWS for 24 hours in the "us west 2" region. For more information about this endpoint, we refer to the [API reference documentation](/docs/api-reference/computing#vm-instance)
.
#### Request[](#request)
curl --request POST \ --url https://api.climatiq.io/compute/v1/aws/instance \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "instance": "t2.nano", "region": "us_west_2", "duration": 24, "duration_unit": "h"}'
#### Response[](#response)
{ "total_co2e": 0.03879, "total_co2e_unit": "kg", "memory_estimate": { "co2e": 0.001575, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "73cf8c76-3be9-4942-ac09-201cf572e3a1", "access_type": "public", "source": "EPA", "source_dataset": "eGRID", "year": 2022, "region": "US-NWPP", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.001575, "co2e_other": null, "co2": 0.001566, "ch4": 1.456e-7, "n2o": 2.08e-8 }, "activity_data": { "activity_value": 0.005733, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "EPA", "source_dataset": "eGRID", "year": "2022", "region": "US-NWPP", "region_name": "WECC Northwest, US" } ] }, "cpu_estimate": { "co2e": 0.01587, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "73cf8c76-3be9-4942-ac09-201cf572e3a1", "access_type": "public", "source": "EPA", "source_dataset": "eGRID", "year": 2022, "region": "US-NWPP", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.01587, "co2e_other": null, "co2": 0.01577, "ch4": 0.000001467, "n2o": 2.096e-7 }, "activity_data": { "activity_value": 0.05775, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "EPA", "source_dataset": "eGRID", "year": "2022", "region": "US-NWPP", "region_name": "WECC Northwest, US" } ] }, "embodied_cpu_estimate": { "co2e": 0.02135, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "AWS - Embodied emissions - t2.nano - Xeon E5-2676 v3", "activity_id": "cpu-provider_aws-type_t2.nano_xeon_e5_2676_v3", "id": "7a8ff5fd-3361-427b-aedf-e47a5e49ea82", "access_type": "public", "source": "CCF", "source_dataset": "Derived from CCF models", "year": 2021, "region": "GLOBAL", "category": "Cloud Computing - CPU", "source_lca_activity": "upstream-end_of_life", "data_quality_flags": [ "notable_methodological_variance" ] }, "constituent_gases": { "co2e_total": 0.02135, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 24, "activity_unit": "instance-hour" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "AWS - Embodied emissions - t2.nano - Xeon E5-2676 v3", "source": "CCF", "source_dataset": "Derived from CCF models", "year": "2021", "region": "GLOBAL", "region_name": "Global" } ] }, "calculation_details": { "instance": "t2.nano", "instance_memory": 0.536870912, "memory_unit": "GB", "vcpu_cores": 1, "average_vcpu_utilization": 0.5, "power_usage_effectiveness": 1.135, "energy_used_cpu": 0.0577488, "energy_used_memory": 0.00573275054800896, "energy_unit": "kWh" }}
**Selecting electricity emission factors**
When viewing or overriding electricity emission factors, a number of aspects need to be taken into account including; what particular mix of energy is being provided by the source, whether the factor includes upstream emissions and whether it includes transmission and distribution losses. This information is encoded in the `activity_id` and the `source_lca_activity` fields provided in API response. More information can be retrieved from the issuing source. Read more about selecting electricity EFs [here](/docs/guides/understanding/selecting-electricity-efs)
.
Carbon Emissions for Other Services[](#carbon-emissions-for-other-services)
----------------------------------------------------------------------------
For many services, you aren't renting a complete VM, but instead, leasing some storage, memory, or CPU power. Even in these cases, Climatiq can assist you. Endpoints are available for estimating emissions based on [storage reserved](/docs/api-reference/computing#storage)
, [memory available](/docs/api-reference/computing#memory)
or [virtual CPU power used](/docs/api-reference/computing#cpu)
Depending on the service, obtaining these metrics might pose different levels of difficulty. This guide doesn't cover the specifics of retrieving these metrics, but a good starting point could be your cloud provider's monitoring systems or your billing/usage data. If you need further assistance, refer to [this document (opens in a new tab)](https://www.cloudcarbonfootprint.org/docs/methodology/)
, or your cloud provider's documentation.
Let's take a couple of examples of how we can use the Climatiq endpoints to measure based on this more granular input.
### CPU Example: Serverless Functions[](#cpu-example-serverless-functions)
If you are running serverless functions, you are often able to retrieve the CPU usage from monitoring or billing. Let's consider an AWS Lambda function with the following specifications:
* Function runtime: 200ms
* CPU usage: 1 vCPU core
* Location: US West (Oregon) (see [this link for a detailed guide of AWS regions (opens in a new tab)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions)
)
The emissions from this function's CPU usage can be calculated using Climatiq's [CPU endpoint](/docs/api-reference/computing#cpu)
like this.
#### Request[](#request-1)
curl --request POST \ --url https://api.climatiq.io/compute/v1/aws/cpu \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "cpu_count": 1, "region": "us_west_2", "duration": 200, "duration_unit": "ms"}'
#### Response[](#response-1)
{ "co2e": 3.674e-8, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "73cf8c76-3be9-4942-ac09-201cf572e3a1", "access_type": "public", "source": "EPA", "source_dataset": "eGRID", "year": 2022, "region": "US-NWPP", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 3.674e-8, "co2e_other": null, "co2": 3.651e-8, "ch4": 3.396e-12, "n2o": 4.851e-13 }, "activity_data": { "activity_value": 1.337e-7, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "EPA", "source_dataset": "eGRID", "year": "2022", "region": "US-NWPP", "region_name": "WECC Northwest, US" } ]}
### Memory Example: Serverless Functions[](#memory-example-serverless-functions)
To account for the carbon emissions linked to memory (RAM) usage, one must consider both the allocated and the actually used memory.
Even if the full memory isn't used, it still consumes power. a good rule of thumb is to use the total amount of RAM you have allocated, not just the amount you use.
For our AWS Lambda function, consider the following specification:
* Function runtime: 200ms
* Memory allocated: 1792MB
The emissions from this function's memory usage can be calculated using Climatiq's [Memory endpoint](/docs/api-reference/computing#memory)
like this.
#### Request[](#request-2)
curl --request POST \ --url https://api.climatiq.io/compute/v1/aws/memory \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "region": "us_west_2", "data": 1792, "data_unit": "MB", "duration": 200, "duration_unit": "ms"}'
#### Response[](#response-2)
{ "co2e": 1.217e-8, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "73cf8c76-3be9-4942-ac09-201cf572e3a1", "access_type": "public", "source": "EPA", "source_dataset": "eGRID", "year": 2022, "region": "US-NWPP", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 1.217e-8, "co2e_other": null, "co2": 1.21e-8, "ch4": 1.125e-12, "n2o": 1.607e-13 }, "activity_data": { "activity_value": 4.429e-8, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "EPA", "source_dataset": "eGRID", "year": "2022", "region": "US-NWPP", "region_name": "WECC Northwest, US" } ]}
Combining the CPU and memory usage for this serverless function will then give you a good idea of the use phase emissions.
### Storage[](#storage)
Storage in cloud computing not only consumes power but also varies in terms of the backing hardware and replication strategies.
To calculate storage emissions, consider the following aspects:
1. The type of hardware backing your storage: HDDs generally consume less power but are slower than SSDs.
2. Calculate emissions based on storage purchased, not just used. Even if you're not using the storage, having it available will use electricity.
3. Replication: storage is often duplicated across multiple machines or data centers. If your storage is replicated you should take your storage amount and multiply it by how many times it's replicated. You'll have to look at your cloud provider and the specific services you use to figure out how many times data is replicated. Here's a [list of list of replication factors (opens in a new tab)](https://docs.google.com/spreadsheets/d/1D7mIGKkdO1djPoMVmlXRmzA7_4tTiGZLYdVbfe85xQM/edit?usp=sharing)
, which covers many services for all the major cloud providers.
Two examples are presented below, one considering SSD instance storage on EC2 and the other taking into account usage of S3 for file storage. Each case illustrates how these factors affect carbon emissions calculations.
#### Storage Example 1. An SSD EC2 Instance Storage[](#storage-example-1-an-ssd-ec2-instance-storage)
In this example, we mount a 20GB SSD instance storage on our EC2 instance, and we want to calculate the emissions over a week.
Looking at the [AWS replication factors (opens in a new tab)](https://docs.google.com/spreadsheets/d/1D7mIGKkdO1djPoMVmlXRmzA7_4tTiGZLYdVbfe85xQM/edit?usp=sharing)
, the EC2 Instance Storage is not replicated. This means we only have estimate with the data we've purchased.
##### Request[](#request-3)
curl --request POST \ --url https://api.climatiq.io/compute/v1/aws/storage \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "region": "us_west_2", "data": 20, "data_unit": "GB", "storage_type": "ssd", "duration": 7, "duration_unit": "day"}'
##### Response[](#response-3)
{ "co2e": 0.001258, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "73cf8c76-3be9-4942-ac09-201cf572e3a1", "access_type": "public", "source": "EPA", "source_dataset": "eGRID", "year": 2022, "region": "US-NWPP", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.001258, "co2e_other": null, "co2": 0.00125, "ch4": 1.162e-7, "n2o": 1.661e-8 }, "activity_data": { "activity_value": 0.004576, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "EPA", "source_dataset": "eGRID", "year": "2022", "region": "US-NWPP", "region_name": "WECC Northwest, US" } ]}
#### Storage Example 2: Using S3[](#storage-example-2-using-s3)
Let's take a slightly harder example, where we try to calculate emissions based on the use of S3 to store files.
This is harder for several reasons:
* Hardware: Amazon has never published which sort of physical storage they use in S3, but it's generally safe to assume that cheaper HDDs are primarily used so we'll use the HDD emission factor.
* Pre-allocation: Unlike certain services, S3 doesn't require pre-allocation of storage. You pay for what you store. It's likely that you share hard-drives with other consumers so we only consider the amount of storage actually used.
* Replication: S3 data is replicated in 3 different locations, meaning we'll need to take the amount we've stored and multiply it by 3.
For instance, if we're storing 5GB in S3, we'd use the HDD emission factor and an amount of "15GB". The latter is because the data is replicated three times, effectively using 15GB of storage. The resulting CO2e emissions for storing this data for a week are calculated below.
##### Request[](#request-4)
curl --request POST \ --url https://api.climatiq.io/compute/v1/aws/storage \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "region": "us_west_2", "data": 15, "data_unit": "GB", "storage_type": "hdd", "duration": 7, "duration_unit": "day"}'
##### Response[](#response-4)
{ "co2e": 0.0005109, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "73cf8c76-3be9-4942-ac09-201cf572e3a1", "access_type": "public", "source": "EPA", "source_dataset": "eGRID", "year": 2022, "region": "US-NWPP", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.0005109, "co2e_other": null, "co2": 0.0005077, "ch4": 4.722e-8, "n2o": 6.746e-9 }, "activity_data": { "activity_value": 0.001859, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "EPA", "source_dataset": "eGRID", "year": "2022", "region": "US-NWPP", "region_name": "WECC Northwest, US" } ]}
**Underlying methodology**
Climatiq relies on the [Cloud Carbon Footprint (opens in a new tab)](https://www.cloudcarbonfootprint.org/docs/methodology)
methodology for most of our assumptions such as the power-usage of memory and vCPU's. While the CCF methodology allows for specific power calculations based on the underlying hardware, Climatiq currently only uses an average watts per vCPU per provider, and not architecture specific power consumption data.
Summary[](#summary)
--------------------
This guide provides a solid foundation on how to calculate the carbon emissions of your cloud computing usage. While Climatiq's emission factors are comprehensive for many aspects of cloud computing, it doesn't cover areas such as network traffic to the end-user, or network traffic between your servers.
For a more accurate and complex assessment, don't hesitate to [get in touch (opens in a new tab)](https://www.climatiq.io/contact-us)
. Together, we can make your cloud computing greener and more sustainable.
[Upload and Use Private Emission Factors](/docs/guides/tutorials/private-emission-factors "Upload and Use Private Emission Factors")
[Use Classification Codes](/docs/guides/tutorials/classification-codes "Use Classification Codes")
---
# Upload and Use Private Emission Factors - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Upload and Use Private Emission Factors
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](https://www.climatiq.io/pricing)
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[](#upload-private-emission-factors-via-the-climatiq-dashboard)
--------------------------------------------------------------------------------------------------------------------------
### Log in to your Climatiq Dashboard.[](#log-in-to-your-climatiq-dashboard)
[Log in to your Climatiq (opens in a new tab)](https://app.climatiq.io)
account and click on the Private Factors item in the sidebar.
### Click on _Add emission factors_[](#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[](#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](/docs/guides/private-emission-factors#appendix-data-structure-for-private-emission-factors)
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[](#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_
### Wait for the private emission factors to be validated[](#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:
### Replace a private emission factor[](#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[](#using-your-private-factors)
----------------------------------------------------------
To use a private emission factor in an estimate:
### Make a request to the `/estimate` endpoint.[](#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[](#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[](#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](/docs/api-reference/estimate#request)
. | 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`\* | A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor applies. | Valid country code (based on [UN-LOCODEs (opens in a new tab)](https://unece.org/trade/cefact/unlocode-code-list-country-and-territory)
). |
| `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](/docs/api-reference/unit-types)
. |
| `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](/docs/guides/tutorials/quickstart "Quickstart")
[Calculate Cloud Carbon Footprint](/docs/guides/tutorials/cloud "Calculate Cloud Carbon Footprint")
---
# Procurement - Climatiq API Reference - Automated Carbon Emission Calculations
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[](#procurement-endpoint)
----------------------------------------------
POST This endpoint automatically calculates basic prices for use with [EXIOBASE (opens in a new tab)](https://www.climatiq.io/data/source/exiobase)
. 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[](#request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* activityrequired [ActivityDescription](/docs/api-reference/procurement#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](/docs/api-reference/intermodal-freight)
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](/docs/api-reference/models/parameters#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.
Default Value
Margin extracted from EXIOBASE
* 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.
Default Value
Margin extracted from EXIOBASE
* 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.
Default Value
Margin extracted from EXIOBASE
#### ActivityDescription[](#activitydescription)
You can describe the activity either by using a [classification code](/docs/guides/tutorials/classification-codes)
and classification scheme, or an activity ID.
##### Classification Code[](#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-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[](#response)
The response includes the CO2e estimate and details about the calculation.
Response parameters
* estimate[Estimation](/docs/api-reference/models/estimation#estimation)
_object_
The estimation performed returning the total CO2e value, constituent gases and more.
* calculation\_details_object_
Details about the calculation, including applied tax, trade, and transport margins and inflation. Note that this is only returned if [audit trail](/docs/api-reference/audit-trail)
is enabled, otherwise it is `null`.
✖ Hide child attributes
* * *
calculation\_details\[x\].tax\_margin_number_
Details about the calculation, including applied tax, trade, and transport margins and inflation. Note that this is only returned if [audit trail](/docs/api-reference/audit-trail)
is enabled, otherwise it is `null`.
* * *
calculation\_details\[x\].trade\_margin_number_
The trade margin applied in the calculation.
* * *
calculation\_details\[x\].transport\_margin_number_
The transport margin applied in the calculation.
* * *
calculation\_details\[x\].inflation\_applied_number_
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.
* notices_array of [Notices](/docs/api-reference/procurement#notice)
_
Any notices related to the calculation.
* source\_trail_array of [Source Data Point](/docs/api-reference/source-trail#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](/docs/api-reference/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[](#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 Value | Description |
| --- | --- |
| `partial_inflation_adjustment` | Inflation adjustment was applied only partially, not covering the entire period. |
| `no_inflation_adjustment` | No 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_applied` | No valid tax margin was found to apply to the procurement's basic price. |
| `tax_margin_not_applied` | No valid tax margin was found to apply to the procurement's basic price. |
| `transport_margin_not_applied` | No valid tax margin was found to apply to the procurement's basic price. |
### Batch Procurement Endpoint[](#batch-procurement-endpoint)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
[Freight v2 (preview 1)](/docs/api-reference/intermodal-freight/intermodal-freight-v2-preview1 "Freight v2 (preview 1)")
[Classifications](/docs/api-reference/classifications "Classifications")
---
# Travel - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Travel (preview)
Travel 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 three months. Read more about API versioning at Climatiq [here](/docs/guides/understanding/api-versioning)
.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](https://www.climatiq.io/contact-us)
.
Climatiq provides a comprehensive toolkit to help businesses measure GHG emissions from travel activities. This includes reporting scope 3.6 emissions under the GHG Protocol for travel activities in vehicles owned or operated by third parties, such as aircraft, trains and passenger cars. Emissions associated with hotel stays can also be calculated, providing a comprehensive view of travel-related emissions.
The GHG Protocol outlines three main methods for calculating GHG emissions from your travels:
* Fuel-based
* Distance-based
* Spend-based
Your choice of method will depend on the data you have at hand.
Our endpoints are tailored to handle all possible situations with respect to your data availability. Use our spend-based endpoint if you only have expenditure data available. For enhanced accuracy, the distance-based endpoint offers route-specific estimates, automatic distance calculations, and customization options to improve calculations.
Notes on calculation methods:
* The Travel feature provides endpoints for distance-based and spend-based approaches where you have distance or spend data.
* If you have fuel usage data (e.g. liters of petrol), use our [Estimate](/docs/api-reference/estimate)
endpoint or [Energy](/docs/api-reference/energy)
feature.
* To calculate emissions from taxi journeys, use the distance-based method when you have data on the vehicle type and the journey's origin and destination. Alternatively, use the spend-based method if you know the cost of the taxi.
Distance-based method[](#distance-based-method)
------------------------------------------------
POST This endpoint allows you to apply the distance-based method by specifying the origin and destination of your journey, and the primary mode of transportation: by air, car, or rail. The journey distance is automatically determined and used for the calculation.
The endpoint will return the CO2e for the primary mode of transportation. If the journey includes separate legs (e.g. travel to / from a railway station or airport) then these need to be calculated separately with additional calls to the API.
https://preview.api.climatiq.io/travel/v1-preview1/distance
**Notes**
* The endpoint works for one-way travel for one passenger. If your journey has more legs (e.g. is a return journey / round trip) or passengers, you should make multiple API calls.
* We do not have full coverage of the global rail network. If data on specific rail segments is missing, we might use car routes for distance calculations instead of rail routes.
* For air travel, the endpoint will always include a [Radiative Forcing (opens in a new tab)](https://unhsimap.org/cmap/resources/air-travel)
(RF) multiplier. It is best practice to include the RF multiplier in most reporting although sometimes (e.g. under the SBTi) it is not accounted for.
* For electricity-based estimates, such as electric vehicles, the CO2e values returned are location-based, not market-based. Find more details on the different types of electricity-based estimates in our [Energy feature](/docs/api-reference/energy)
.
### Request[](#request)
Request parametersShould be sent as a JSON object in the body
* travel\_moderequired string
The primary type of travel for this journey. Valid values are: `air`, `car`, `rail`.
* originrequired object
The origin of the journey. Accepts [QueryLocation](/docs/api-reference/regions#query-location)
, [IataCodeLocation](/docs/api-reference/regions#iata-code-location)
, [UNLocodeLocation](/docs/api-reference/regions#unlocode-location)
or [CoordinateLocation](/docs/api-reference/regions#coordinate-location)
.
* destinationrequired object
The destination of the journey. Accepts [QueryLocation](/docs/api-reference/regions#query-location)
, [IataCodeLocation](/docs/api-reference/regions#iata-code-location)
, [UNLocodeLocation](/docs/api-reference/regions#unlocode-location)
or [CoordinateLocation](/docs/api-reference/regions#coordinate-location)
.
* yearinteger
Default value: Latest year available
The year that the travel occurred.
Default Value
Latest year available
* distance\_kmfloat
If you have an actual distance for this leg in kilometers you can input the distance here. Climatiq will then use this distance instead of the planned distance it would normally calculate.
* car\_detailsobject
Additional details about the car used for the travel. Supplying this will result in more accurate estimations. Can only be used when `travel_mode` is `car`.
➕ Show child attributes
* air\_detailsobject
Additional details about the plane used for the travel. Supplying this will result in more accurate estimations. Can only be used when `travel_mode` is `air`.
➕ Show child attributes
#### Car Sizes[](#car-sizes)
The `car_details` object allows you to specify different car types that you can see in the list below. If you don't know the size of the car used for the trip, you can omit the `car_size` or set it as `average`, both of which will result in a weighted average of car sizes on the road being used.
| Car size | Petrol | Diesel | Others | Car example |
| --- | --- | --- | --- | --- |
| `small` | below 1.4-liter engine | below 1.7-liter engine | Vehicle models of a similar size (i.e. [market segment A or B (opens in a new tab)](https://en.wikipedia.org/wiki/Euro_Car_Segment)
) | Fiat 500, Opel Adam, Renault Clio, Ford Fiesta etc. |
| `medium` | from 1.4-liter to 2.0-liter engine | from 1.7-liter to 2.0-liter engine | Vehicle models of a similar size (i.e. generally market segment C) | Volkswagen Golf, Honda Civic etc. |
| `large` | above 2-liter engine | above 2-liter engine | Vehicle models of a similar size (i.e. generally market segment D and above) | BMW 3-Series, Volkswagen Passat etc. |
curl --request POST \ --url https://preview.api.climatiq.io/travel/v1-preview1/distance \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "origin": { "locode": "DE-HAM" }, "destination": { "query": "Berlin" }, "travel_mode": "car", "car_details": { "car_type": "plugin_hybrid" }}'
### Response[](#response)
A response consists of the following attributes.
Response parameters
* co2efloat
The total co2e emitted by the journey, expressed in co2e\_unit.
* co2e\_unitstring
Always `kg`.
* co2e\_calculation\_methodstring
Which calculation methodology that was used for the calculation. The value of this is either `ipcc_ar4_gwp100`, `ipcc_ar5_gwp100`, `ipcc_ar6_gwp100` or `ipcc_mixed_gwp100`.
[Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation)
* distance\_kmfloat
The distance in kilometers of the journey using the primary mode of transport (excludes any travel to and from airport or railway stations).
* originobject
A [ResponseLocation](/docs/api-reference/travel#response-location)
containing the `name` and an (optional) `confidence_score` of the location we found, given your `origin` parameter.
* destinationobject
A [ResponseLocation](/docs/api-reference/travel#response-location)
containing the `name` and an (optional) `confidence_score` of the location we found, given your `destination` parameter.
* direct\_emissionsobject
The emissions associated with the direct emissions of the journey, such as the combustion of fuel or generation of electricity. For air flights, the radiative forcing effect is included in these emissions.
* indirect\_emissionsobject
The upstream emissions associated with the journey, such as transmission and distribution losses for electricity, or the extraction and transportation of the fuel (i.e. well-to-tank).
* noticesarray of [Notices](/docs/api-reference/travel#notice)
Any [notices](/docs/api-reference/travel#notice)
related to the calculation.
* source\_trailarray of [SourceDataPoint](/docs/api-reference/source-trail#source-data-point)
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about [Source Trail](/docs/api-reference/source-trail)
. **This field is deprecated - please use the `source_trail` inside the `direct_emissions` and `indirect_emissions` fields.**
{ "co2e": 44.28, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_mixed_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid - production mix", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2022", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Petrol (100% mineral petrol)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" } ], "distance_km": 299.1, "origin": { "name": "Hamburg", "latitude": 53.51666, "longitude": 9.93333, "confidence_score": null }, "destination": { "name": "Berlin, Germany", "latitude": 52.51604, "longitude": 13.37691, "confidence_score": 1 }, "direct_emissions": { "co2e": 34.26, "co2e_unit": "kg", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid - production mix", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2022", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Petrol (100% mineral petrol)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" } ] }, "indirect_emissions": { "co2e": 10.02, "co2e_unit": "kg", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid - production mix", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2022", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Petrol (100% mineral petrol)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" } ] }, "notices": []}
Spend-based method[](#spend-based-method)
------------------------------------------
POST This endpoint uses EXIOBASE emission factors to calculate emissions based on your spending on travel activities in any currency. This endpoint automatically takes inflation into account, if the year you spent the money was different than the year of the emission factor. Note that the EXIOBASE spend-based emission factor, used for the road travel is, in fact, an average emission factor for a mix of different types of transport: urban and suburban passenger land transport, taxi operation, other passenger land transport and freight transport by road and can therefore produce results of lower accuracy. Climatiq advises to use fuel-based or distance-based method, where possible.
https://preview.api.climatiq.io/travel/v1-preview1/spend
### Request[](#request-1)
Request parametersShould be sent as a JSON object in the body
* spend\_typerequired string
The type of travel associated with the expenditure. Valid values are: `air`, `road`, `rail`, `sea`, and `hotel`.
* moneyrequired float
The amount of money spent.
* money\_unitrequired string
The currency in which the money unit is expressed.
* spend\_locationrequired object
The location where money was spent. Accepts [QueryLocation](/docs/api-reference/regions#query-location)
, [IataCodeLocation](/docs/api-reference/regions#iata-code-location)
, [UNLocodeLocation](/docs/api-reference/regions#unlocode-location)
or [CoordinateLocation](/docs/api-reference/regions#coordinate-location)
.
* spend\_yearinteger
Default value: Latest year available
The year in which expenditures occurred.
Default Value
Latest year available
curl --request POST \ --url https://preview.api.climatiq.io/travel/v1-preview1/spend \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "spend_type": "air", "money": 100, "money_unit": "gbp", "spend_location": { "locode": "GB-LON" }, "spend_year": 2018}'
### Response[](#response-1)
Response parameters
* co2efloat
co2e emitted by the journey, expressed in co2e\_unit.
* co2e\_unitstring
Always `kg`.
* co2e\_calculation\_methodstring
Which calculation methodology that was used for the calculation. The value of this is either `ipcc_ar4_gwp100`, `ipcc_ar5_gwp100`, `ipcc_ar6_gwp100` or `ipcc_mixed_gwp100`.
[Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation)
* spend\_locationobject
A [ResponseLocation](/docs/api-reference/travel#response-location)
containing the `name` and an (optional) `confidence_score` of the location we found, given your `spend_location` parameter.
* noticesarray of [Notices](/docs/api-reference/travel#notice)
Any [notices](/docs/api-reference/travel#notice)
related to the calculation.
* source\_trailarray of [SourceDataPoint](/docs/api-reference/source-trail#source-data-point)
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about [Source Trail](/docs/api-reference/source-trail)
.
{ "co2e": 135.5, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": null, "name": "Country-specific inflation rates", "source": "World Bank", "source_dataset": null, "year": null, "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Air transport services", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": "2019", "region": "GB", "region_name": "United Kingdom" } ], "spend_location": { "name": "London, LND, GB", "latitude": 51.50643, "longitude": -0.12718, "confidence_score": null }, "notices": []}
Hotels[](#hotels)
------------------
POST Use this endpoint to estimate emissions from hotel stays across the world based on the number of nights spent. If no emission factor is available for hotels in the given country, another factor from the same continent is used.
https://preview.api.climatiq.io/travel/v1-preview1/hotel
### Request[](#request-2)
Request parametersShould be sent as a JSON object in the body
* hotel\_nightsrequired integer
The number of nights spent in the hotel.
* locationrequired object
The location of the hotel. Accepts [QueryLocation](/docs/api-reference/regions#query-location)
, [IataCodeLocation](/docs/api-reference/regions#iata-code-location)
, [UNLocodeLocation](/docs/api-reference/regions#unlocode-location)
or [CoordinateLocation](/docs/api-reference/regions#coordinate-location)
.
* yearinteger
Default value: Latest year available
The year that the hotel stay occurred.
Default Value
Latest year available
curl --request POST \ --url https://preview.api.climatiq.io/travel/v1-preview1/hotel \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "hotel_nights": 5, "location": { "query": "San Francisco" }}'
### Response[](#response-2)
Response parameters
* co2efloat
co2e emitted by the hotel stay, expressed in co2e\_unit.
* co2e\_unitstring
Always `kg`.
* co2e\_calculation\_methodstring
Which calculation methodology that was used for the calculation. The value of this is either `ipcc_ar4_gwp100`, `ipcc_ar5_gwp100`, `ipcc_ar6_gwp100` or `ipcc_mixed_gwp100`.
[Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation)
* noticesarray of [Notices](/docs/api-reference/travel#notice)
Any [notices](/docs/api-reference/travel#notice)
related to the calculation.
* locationobject
A [ResponseLocation](/docs/api-reference/travel#response-location)
containing the `name` and an (optional) `confidence_score` of the location we found, given your `location` parameter.
* source\_trailarray of [SourceDataPoint](/docs/api-reference/source-trail#source-data-point)
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about [Source Trail](/docs/api-reference/source-trail)
.
{ "co2e": 80.5, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Hotel stay", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2024", "year": "2024", "region": "US", "region_name": "United States of America (the)" } ], "location": { "name": "United States of America (the)", "confidence_score": 1 }, "notices": []}
Response Location[](#response-location)
----------------------------------------
Many endpoints return locations back to you. These locations will contain the following properties
| Response Location attributes |
| --- |
| **name** _string_
A human-readable name of the location. |
| **latitude** _string_ or _null_
The latitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled. |
| **longitude** _string_ or _null_
The longitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled. |
| **confidence\_score** _float_
A confidence score between 0 and 1, determining how certain we are that the location matches your query. Only exists if the input location was a `QueryLocation`. |
Notice[](#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 value | description |
| --- | --- |
| `partial_inflation_adjustment` | Inflation adjustment was applied only partially, not covering the entire period. |
| `no_inflation_adjustment` | No 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. |
| `location_fallback` | Factors or calculation methods for the exact location are not available, we have used a fallback location which we believe best covers the specified location. |
| `routing_fallback` | It was not possible to find a route given the current parameters. A different routing mechanism was used instead. |
[Custom Mappings](/docs/api-reference/custom-mappings "Custom Mappings")
[Autopilot (preview 3)](/docs/api-reference/autopilot "Autopilot (preview 3)")
---
# Cloud Computing - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Cloud Computing
Cloud Computing ADD-ONADD-ON
============================
Climatiq makes endpoints available to help you calculate the carbon footprint of the cloud resources you use. It will automatically select emission factors based on your cloud provider and region, so you get the right emission factor for your datacenter.
All the cloud computing endpoints expect you to provide the cloud provider in the url. Where the urls state `:provider` you must replace it with a supported cloud provider. You can view the supported cloud providers by using the [metadata endpoint](/docs/api-reference/computing#metadata)
For examples of how to perform calculations for specific services, or extra information about our methodology, please view the [Cloud Computing Guide](/docs/guides/tutorials/cloud)
Metadata[](#metadata)
----------------------
GET Returns metadata, such as what sort of providers and regions are available for the different computing endpoints.
### Request[](#request)
https://api.climatiq.io/compute/v1/metadata
### Response[](#response)
The endpoint will return metadata for all cloud computing endpoints.
Response parameters
* cloud\_providersstring
An object where each key is the id for a cloud provider, and the corresponding value contains additional data about that cloud provider.
✖ Hide child attributes
* * *
cloud\_providers\[x\].provider\_full\_name_string_
The full, human-readable name for the provider
* * *
cloud\_providers\[x\].provider\_id_string_
The id of the cloud provider. This is the value you must use when specifying provider in the computing endpoints.
* * *
cloud\_providers\[x\].regionsarray of _strings_
The different available regions for this provider.
* * *
cloud\_providers\[x\].virtual\_machine\_instancesarray of _strings_
The different instances you can use in the [Virtual Machine Instance endpoint](/docs/api-reference/computing#vm-instance)
for this provider.
{ "cloud_providers": { "aws": { "provider_full_name": "Amazon Web Services", "provider_id": "aws", "regions": [ "af_south_1", "ap_east_1", "ap_northeast_1" // ... ], "virtual_machine_instances": [ "a1.medium", "a1.large", "a1.xlarge", "a1.2xlarge", "a1.4xlarge", "a1.metal", "c1.medium" // ... ] }, "azure": { "provider_full_name": "Microsoft Azure", "provider_id": "azure", "regions": [ "central_india", "central_us" // ... ] // ... } // More providers here }}
VM Instance[](#vm-instance)
----------------------------
POST Calculate total estimated emissions based on the usage of a specific virtual machine instance. This endpoint estimates both the embodied emissions (meaning the emissions related to the manufacturing and disposal of the physical components, expressed per CPU hour over the expected lifetime of the hardware) and the electricity usage of the different components.
https://api.climatiq.io/compute/v1/:provider/instance
Where the `:provider` path argument must be replaced with the id of the supported cloud providers. You can retrieve the different ids from the [computing metadata endpoint](/docs/api-reference/computing#metadata)
### Request[](#instance-request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* regionrequired string
The region that is relevant for the calculation, as specified by the cloud provider.
* instancerequired string
The specific virtual machine instance type you are using. You may query the [metadata endpoint](/docs/api-reference/computing#metadata)
to get a list of valid instances for each provider.
* durationrequired float
How long the machine is running for.
* duration\_unitstring
Default value: `hour`
The unit the `duration` value is in. The values accepted here are the same as in the [Time](/docs/api-reference/models/parameters#time)
unit.
Default Value
`hour`
* yearinteger
Default value: Latest year available
The year that the computing resources were used. Climatiq will pick emission factors that is as close to the supplied year as possible.
Default Value
Latest year available
* average\_vcpu\_utilizationfloat
Default value: `0.5`
How much the vCPU's on the instance are utilized in the given timeframe you are estimating for. Must be a number between `0` and `1`
Default Value
`0.5`
* overridesOverrides _object_
If you need more fine-grained control over some behavior, you may specify an object with `overrides` to further customize the endpoint behavior.
✖ Hide child attributes
* * *
overrides\[x\].Power usage effectiveness[number](https://www.techtarget.com/searchdatacenter/definition/power-usage-effectiveness-PUE)
_object_
The power usage effectiveness (PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.
* * *
overrides\[x\].Electricity emission factor[Selector](/docs/api-reference/models/selector)
_object_
By default Climatiq selects an appropriate high-quality electricity emission factor for the geographical region your instance is located in. If you want to override this selection you may supply a Selector here. If you do that, you have full control over selecting an emission factor. The emission factor must have the `Energy` unit type.
curl --request POST \--url https://api.climatiq.io/compute/v1/azure/instance \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "region": "uk_west", "instance": "h8", "duration": 24, "duration_unit": "h"}'
**Different CPU architectures**
In a few cases, the same instance might have different embodied emissions depending on the underlying CPU architecture that powers the instance. There's no way to find out the underlying architecture.
In cases like that, Climatiq will be conservative and assume the most CO2e-intensive CPU architecture.
### Response[](#instance-response)
The response includes a list of estimates for the different components of using an instance.
Response parameters
* cpu\_estimate_[EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
_
An estimate corresponding to the electricity used for the CPU part of the instance.
* memory\_estimate_[EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
_
An estimate corresponding to the electricity used for the memory (RAM) part of the instance.
* embodied\_cpu\_estimate_[EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
_
An estimate corresponding to the embodied emissions, meaning the emissions related to the manufacturing and disposal of the physical components, of the CPU part of this instance. This is expressed per CPU hour over the expected lifetime of the hardware.
* calculation\_details_object_
Metadata about the calculation to better understand the results.
✖ Hide child attributes
* * *
calculation\_details\[x\].instancestring
The string identifying the instance type selected
* * *
calculation\_details\[x\].instance\_memorynumber
The memory in `memory_unit` that the given instance has. This is what's used as the basis for `memory_estimate`.
* * *
calculation\_details\[x\].memory\_unitstring
The unit that the `instance_memory` is expressed in. Is currently always `GB` (Gigabytes)
* * *
calculation\_details\[x\].vcpu\_coresnumber
The amount of virtual CPU cores the instance has.
* * *
calculation\_details\[x\].average\_vcpu\_utilizationnumber
The average utilization over all virtual CPU cores of the instance.
* * *
calculation\_details\[x\].power\_usage\_effectivenessnumber
The power usage effectiveness used in the calculations.
* * *
calculation\_details\[x\].energy\_used\_cpunumber
The total amount of energy, expressed in `energy_unit`, used by the CPU part of the instance.
* * *
calculation\_details\[x\].energy\_used\_memorynumber
The total amount of energy, expressed in `energy_unit`, used by the memory part of the instance.
* * *
calculation\_details\[x\].energy\_unitstring
The unit that energy usage is expressed in. Is currently always `kWh` (kilowatt-hours)
**Double counting of memory**
The underlying data for the CPU estimates are based on power benchmarks of CPUs that includes some degree of memory as well. Climatiq does not currently take that into account when performing memory estimates. This means there can be some degree of over-estimation happening, as some of the memory might be estimated as part of the CPU, and then again as part of the memory estimate. Climatiq believes it is preferable to include this potential inaccuracy over not including memory in the estimates.
{ "total_co2e": 0.7436, "total_co2e_unit": "kg", "memory_estimate": { "co2e": 0.1382, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "0de2d70a-4704-48f4-b862-1a86da206dd3", "access_type": "public", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2024", "year": 2024, "region": "GB", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.1382, "co2e_other": null, "co2": 0.1368, "ch4": 0.00002143, "n2o": 0.000003071 }, "activity_data": { "activity_value": 0.6675, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2024", "year": "2024", "region": "GB", "region_name": "United Kingdom" } ] }, "cpu_estimate": { "co2e": 0.1065, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "0de2d70a-4704-48f4-b862-1a86da206dd3", "access_type": "public", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2024", "year": 2024, "region": "GB", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.1065, "co2e_other": null, "co2": 0.1054, "ch4": 0.00001651, "n2o": 0.000002366 }, "activity_data": { "activity_value": 0.5143, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2024", "year": "2024", "region": "GB", "region_name": "United Kingdom" } ] }, "embodied_cpu_estimate": { "co2e": 0.4989, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "AZURE - Embodied emissions - H-series - H8 - Haswell", "activity_id": "cpu-provider_azure-type_h_series_h8_haswell", "id": "1e5983ef-a134-417a-944a-3f1c93b9f61e", "access_type": "public", "source": "CCF", "source_dataset": "Derived from CCF models", "year": 2021, "region": "GLOBAL", "category": "Cloud Computing - CPU", "source_lca_activity": "upstream-end_of_life", "data_quality_flags": [ "notable_methodological_variance" ] }, "constituent_gases": { "co2e_total": 0.4989, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 24, "activity_unit": "instance-hour" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "AZURE - Embodied emissions - H-series - H8 - Haswell", "source": "CCF", "source_dataset": "Derived from CCF models", "year": "2021", "region": "GLOBAL", "region_name": "Global" } ] }, "calculation_details": { "instance": "h8", "instance_memory": 60.129542144000006, "memory_unit": "GB", "vcpu_cores": 8, "average_vcpu_utilization": 0.5, "power_usage_effectiveness": 1.18, "energy_used_cpu": 0.5142912, "energy_used_memory": 0.6675245043390874, "energy_unit": "kWh" }}
### Batch Instance Endpoint[](#batch-instance-endpoint)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/compute/v1/:provider/instance/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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
CPU[](#cpu)
------------
### Estimation[](#estimation)
POST Calculate total estimated use-phase emissions based on the electricity usage for a set number of virtual CPU's (vCPUs)
https://api.climatiq.io/compute/v1/:provider/cpu
Where the `:provider` path argument must be replaced with the id of the supported cloud providers. You can retrieve the different ids from the [computing metadata endpoint](/docs/api-reference/computing#metadata)
#### Request[](#cpu-request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* regionrequired string
The region that is relevant for the calculation, as specified by the cloud provider.
* cpu\_countrequired float
The number of virtual cores you are calculating for. Note that vCPU load is fixed at 50%.
* average\_vcpu\_utilizationfloat
Default value: `0.5`
The average load across all of your vCPU's specified as a float between 0 and 1. If you have two vCPU's that are both working at 100% efficiency across the calculation duration, you would put in 1. If you have four vCPU's where two are working at 100%, and two are working at 50%, you would put in 0.75 here.
Default Value
`0.5`
* durationrequired float
How long the vCPUs are running for.
* duration\_unitstring
Default value: `hour`
The unit the `duration` value is in. The values accepted here are the same as in the [Time](/docs/api-reference/models/parameters#time)
unit.
Default Value
`hour`
* yearinteger
Default value: Latest year available
The year that the computing resources were used. Climatiq will pick emission factors that is as close to the supplied year as possible.
Default Value
Latest year available
* overridesOverrides _object_
If you need more fine-grained control over some behavior, you may specify an object with `overrides` to further customize the endpoint behavior.
✖ Hide child attributes
* * *
overrides\[x\].Power usage effectiveness[number](https://www.techtarget.com/searchdatacenter/definition/power-usage-effectiveness-PUE)
_object_
The power usage effectiveness (PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.
* * *
overrides\[x\].Electricity emission factor[Selector](/docs/api-reference/models/selector)
_object_
By default Climatiq selects an appropriate high-quality electricity emission factor for the geographical region your instance is located in. If you want to override this selection you may supply a Selector here. If you do that, you have full control over selecting an emission factor. The emission factor must have the `Energy` unit type.
curl --request POST \--url https://api.climatiq.io/compute/v1/azure/cpu \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "cpu_count": 1, "region": "uk_west", "average_vcpu_utilization": 0.75, "duration": 1, "duration_unit": "h"}'
#### Response[](#response-1)
You will get an [EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
back with the co2e for the power consumption for the allocated memory for the given duration.
{ "co2e": 0.0007366, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "0de2d70a-4704-48f4-b862-1a86da206dd3", "access_type": "public", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2024", "year": 2024, "region": "GB", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.0007366, "co2e_other": null, "co2": 0.0007291, "ch4": 1.142e-7, "n2o": 1.637e-8 }, "activity_data": { "activity_value": 0.003558, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2024", "year": "2024", "region": "GB", "region_name": "United Kingdom" } ]}
### Batch CPU Endpoint[](#batch-cpu-endpoint)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/compute/v1/:provider/cpu/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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
Storage[](#storage)
--------------------
### Estimation[](#estimation-1)
POST Calculate total estimated use-phase emissions based on the electricity consumption of storing data for a set amount of time.
https://api.climatiq.io/compute/v1/:provider/storage
Where the `:provider` path argument must be replaced with the id of the supported cloud providers. You can retrieve the different ids from the [computing metadata endpoint](/docs/api-reference/computing#metadata)
#### Request[](#storage-request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* regionrequired string
The region that is relevant for the calculation, as specified by the cloud provider.
* storage\_typerequired string
Which type of hard drive the data is stored on. Valid values are `ssd` (solid-state drive) and `hdd` (hard disk drive). The cloud provider does not always specify this for managed services, so you might have to make an informed guess. See our [cloud computing guide](/docs/guides/tutorials/cloud#storage)
for more information.
* datarequired float
How much data is stored. If you use managed services for storage that replicate data across multiple datacenters or hard drives, you might need to take your data amount and multiply it by a replication factor. See our [cloud computing guide](/docs/guides/tutorials/cloud#storage)
for more information.
* data\_unitstring
Default value: `MB`
The unit the `data` value is in. The values accepted here are the same as in the [Data](/docs/api-reference/models/parameters#data)
unit.
Default Value
`MB`
* durationrequired float
How long the data is stored for.
* duration\_unitstring
Default value: `hour`
The unit the `duration` value is in. The values accepted here are the same as in the [Time](/docs/api-reference/models/parameters#time)
unit.
Default Value
`hour`
* yearinteger
Default value: Latest year available
The year that the computing resources were used. Climatiq will pick emission factors that is as close to the supplied year as possible.
Default Value
Latest year available
* overridesOverrides _object_
If you need more fine-grained control over some behavior, you may specify an object with `overrides` to further customize the endpoint behavior.
✖ Hide child attributes
* * *
overrides\[x\].Power usage effectiveness[number](https://www.techtarget.com/searchdatacenter/definition/power-usage-effectiveness-PUE)
_object_
The power usage effectiveness (PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.
* * *
overrides\[x\].Electricity emission factor[Selector](/docs/api-reference/models/selector)
_object_
By default Climatiq selects an appropriate high-quality electricity emission factor for the geographical region your instance is located in. If you want to override this selection you may supply a Selector here. If you do that, you have full control over selecting an emission factor. The emission factor must have the `Energy` unit type.
curl --request POST \--url https://api.climatiq.io/compute/v1/aws/storage \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "region": "af_south_1", "storage_type": "ssd", "data": 50, "data_unit": "GB", "duration": 1, "duration_unit": "day"}'
#### Response[](#response-2)
You will get an [EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
back with the CO2e for the storage of the data for the given duration.
{ "co2e": 0.001416, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "90ffe15b-a32a-4a4e-9a49-eccbe3231ca1", "access_type": "public", "source": "CT", "source_dataset": "Climate Transparency Report", "year": 2021, "region": "ZA", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [ "partial_factor" ] }, "constituent_gases": { "co2e_total": 0.001416, "co2e_other": null, "co2": 0.001416, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 0.001634, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "CT", "source_dataset": "Climate Transparency Report", "year": "2021", "region": "ZA", "region_name": "South Africa" } ]}
### Batch Storage Endpoint[](#batch-storage-endpoint)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/compute/v1/:provider/storage/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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
Memory[](#memory)
------------------
### Estimation[](#estimation-2)
POST Calculate total estimated use-phase emissions based on the electricity consumption of having memory (RAM) available for a set amount of time.
https://api.climatiq.io/compute/v1/:provider/memory
Where the `:provider` path argument must be replaced with the id of the supported cloud providers. You can retrieve the different ids from the [computing metadata endpoint](/docs/api-reference/computing#metadata)
#### Request[](#memory-request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* regionrequired string
The region that is relevant for the calculation, as specified by the cloud provider.
* datarequired float
How much memory you have allocated. As memory requires power to be available even if unused, you should put in the amount of memory that you have available - not only the amount you're using.
* data\_unitstring
Default value: `MB`
The unit the `data` value is in. The values accepted here are the same as in the [Data](/docs/api-reference/models/parameters#data)
unit.
Default Value
`MB`
* durationrequired float
How long the memory is available.
* duration\_unitstring
Default value: `hour`
The unit the `duration` value is in. The values accepted here are the same as in the [Time](/docs/api-reference/models/parameters#time)
unit.
Default Value
`hour`
* yearinteger
Default value: Latest year available
The year that the computing resources were used. Climatiq will pick emission factors that is as close to the supplied year as possible.
Default Value
Latest year available
* overridesOverrides _object_
If you need more fine-grained control over some behavior, you may specify an object with `overrides` to further customize the endpoint behavior.
✖ Hide child attributes
* * *
overrides\[x\].Power usage effectiveness[number](https://www.techtarget.com/searchdatacenter/definition/power-usage-effectiveness-PUE)
_object_
The power usage effectiveness (PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.
* * *
overrides\[x\].Electricity emission factor[Selector](/docs/api-reference/models/selector)
_object_
By default Climatiq selects an appropriate high-quality electricity emission factor for the geographical region your instance is located in. If you want to override this selection you may supply a Selector here. If you do that, you have full control over selecting an emission factor. The emission factor must have the `Energy` unit type.
curl --request POST \--url https://api.climatiq.io/compute/v1/gcp/memory \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "region": "us_west_2", "data": 8, "data_unit": "GB", "duration": 24, "duration_unit": "h"}'
#### Response[](#response-3)
You will get an [EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
back with the co2e emitted by having the allocated memory available for the given duration.
{ "co2e": 0.02095, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "a0ac749c-19a5-491e-b301-3517374313ca", "access_type": "public", "source": "Google", "source_dataset": "Carbon data across GCP regions", "year": 2021, "region": "US-LAX", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": [ "self_reported" ] }, "constituent_gases": { "co2e_total": 0.02095, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 0.08279, "activity_unit": "kWh" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "Google", "source_dataset": "Carbon data across GCP regions", "year": "2021", "region": "US-LAX", "region_name": "Los Angeles, CA, US" } ]}
### Batch Memory Endpoint[](#batch-memory-endpoint)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/compute/v1/:provider/memory/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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
[Basic Estimate](/docs/api-reference/estimate "Basic Estimate")
[Custom Mappings](/docs/api-reference/custom-mappings "Custom Mappings")
---
# Using Classification Codes to Estimate Carbon Emissions - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Use Classification Codes
Using Classification Codes to Estimate Carbon Emissions
=======================================================
**This guide explores what classification codes are, the various industry classifications supported, and how to use them with Climatiq.**
⚠️
**Subscription plan required**
This is a paid feature. Please see our [pricing page](https://www.climatiq.io/pricing)
for more details.
What Are Industry Classification Codes?[](#what-are-industry-classification-codes)
-----------------------------------------------------------------------------------
Industry classification codes attempt to categorize human activities into a specific set of categories like "Raising of dairy cattle" or "Rental and leasing of recreational and sports goods". These activities are assigned a unique identifier, known as a **classification code**, under a classification scheme.
Various internationally recognized industry classifications include:
* International Standard Industrial Classification ([ISIC (opens in a new tab)](https://unstats.un.org/unsd/classifications/Econ/isic)
) which is the United Nations industry classification. The latest revision is ISIC4.
* Statistical Classification of Economic Activities in the European Community ([NACE (opens in a new tab)](https://en.wikipedia.org/wiki/Statistical_Classification_of_Economic_Activities_in_the_European_Community)
), which is a european version of ISIC. The latest revision is NACE2
* Merchant Category Codes ([MCC (opens in a new tab)](https://www.citibank.com/tts/solutions/commercial-cards/assets/docs/govt/Merchant-Category-Codes.pdf)
) used to categorize merchants, commonly used for financial transactions.
* United Nations Standard Products and Services Code ([UNSPSC (opens in a new tab)](https://www.unspsc.org/)
), a UN standard used to categorize products and services.
* North American Industry Classification System ([NAICS (opens in a new tab)](https://www.naics.com/)
), which is a standard used by federal statistical agencies in classifying business establishments. The latest revision is NAICS2017.
Classification Codes Supported by Climatiq[](#classification-codes-supported-by-climatiq)
------------------------------------------------------------------------------------------
Climatiq integrates some datasets that publish emission factors along with classification codes. This feature **allows you to estimate carbon emissions based on these classification codes**.
Here's a table of the industry classification codes supported by Climatiq and their corresponding datasets:
| Industry Classification Code | Primary Dataset | Notes |
| --- | --- | --- |
| **[ISIC Rev. 4 (opens in a new tab)](https://unstats.un.org/unsd/classifications/Econ/isic)
** | **[GHG Protocol (opens in a new tab)](https://www.climatiq.io/data/explorer?source=GHG+Protocol&unit_type=Money)
**(via ISIC 3.1) | |
| **[NACE Rev. 2 (opens in a new tab)](https://ec.europa.eu/eurostat/web/products-manuals-and-guidelines/-/ks-ra-07-015)
** | **[EXIOBASE3 (opens in a new tab)](https://www.climatiq.io/data/explorer?source=EXIOBASE)
** | |
| **[Merchant Classification Codes (MCCs) (opens in a new tab)](https://www.citibank.com/tts/solutions/commercial-cards/assets/docs/govt/Merchant-Category-Codes.pdf)
** | **[EXIOBASE3 (opens in a new tab)](https://www.climatiq.io/data/explorer?source=EXIOBASE)
** | |
| **[United Nations Standard Products and Services Code (UNSPSC) (opens in a new tab)](https://www.unspsc.org/)
** | **[EXIOBASE3 (opens in a new tab)](https://www.climatiq.io/data/explorer?source=EXIOBASE)
** | Currently only works for UNSPSC family level codes |
| **[North American Industry Classification System (NAICS) (opens in a new tab)](https://www.naics.com/)
** | **[U.S. Government (EPA) (opens in a new tab)](https://www.climatiq.io/data/source/epa)
** | |
Using Classification Codes to Estimate Carbon Emissions with Climatiq[](#using-classification-codes-to-estimate-carbon-emissions-with-climatiq)
------------------------------------------------------------------------------------------------------------------------------------------------
As an example, let's take the ISIC4 classification code 25, "Manufacture of fabricated metal products, except machinery and equipment". If an emission factor is mapped to the ISIC4 classification scheme and corresponds to the ISIC4 code 25, you can estimate carbon emissions for that classification code as follows:
curl --request POST \--url https://api.climatiq.io/classifications/v1/estimate \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "classification": { "classification_type": "isic4", "classification_code": "25" }, "parameters": { "money": 25.0, "money_unit": "usd" }}'
The resulting response would look like this:
{ "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": "f9682106-3615-4d90-b200-89c7b938a256", "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" } ]}
Tailoring Your Search with Additional Filters[](#tailoring-your-search-with-additional-filters)
------------------------------------------------------------------------------------------------
Multiple emission factors from different datasets might map to the same classification code. If you have a specific emission factor you want to use, you can also filter your selection by specifying a year, source, region or more. [See the full API documentation for more details on what you can filter on](/docs/api-reference/classifications#estimate)
.
**Multiple valid emission factors**
When multiple emission factors satisfy a specific query, Climatiq will select the newest one. If there are multiple emission factors from the same year, the most conservative (highest co2e) is chosen.
Traversing Classification Schemes[](#traversing-classification-schemes)
------------------------------------------------------------------------
Different industry classifications such as ISIC4, NACE2, and others, often share overlapping or identical classification codes. The United Nations provides [correspondence tables (opens in a new tab)](https://unstats.un.org/unsd/classifications/Econ/isic)
to assist in transitioning from one industry classification to another.
Climatiq utilizes these tables to broaden the data available to you. If you query with an NACE2 code that has no corresponding emission factor, Climatiq will attempt to map that NACE2 code to codes available in other industry classifications, such as ISIC4, and if successful, might give you an emission factor based on a corresponding ISIC4 code.
However, transitions between classification schemes aren't perfect. To prevent inaccurate estimates, Climatiq initially searches datasets directly mapped to the classification code you provide (primary datasets in the "supported industry classifications table" above).
Only when no emission factors are found in a primary dataset does Climatiq then search other industry classification schemes.
Remember, after estimating, always review the used emission factor to ensure its validity and accuracy.
[Calculate Cloud Carbon Footprint](/docs/guides/tutorials/cloud "Calculate Cloud Carbon Footprint")
[Create Custom Mappings](/docs/guides/tutorials/custom-mapping-intro "Create Custom Mappings")
---
# Mapping Custom Identifiers to Climatiq Emission Factors - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Create Custom Mappings
Mapping Custom Identifiers to Climatiq Emission Factors
=======================================================
⚠️
**Subscription plan required**
This is a paid feature. Please see our [pricing page](https://www.climatiq.io/pricing)
for more details.
Introduction[](#introduction)
------------------------------
Perhaps the most important step in any emission calculation exercise is the selection of the right emission factor to use for a given emission-generating activity. Traditionally, this process requires intensive labor to establish the right emission factor for each category of activity. Furthermore, this mapping information often finds itself tucked away in a spreadsheet, making it difficult to locate once the initial setup is done.
Climatiq solves this problem with the Custom Mapping tool, available in the [Climatiq dashboard (opens in a new tab)](https://app.climatiq.io)
. This tool empowers Climatiq users to map any identifier they choose to a Climatiq activity ID, which can then be used for emission estimation via the [Custom Mapping endpoint](/docs/api-reference/custom-mappings)
.
This means that there is a persistent place within the Climatiq ecosystem where your activity to emission factor mapping is saved and can be updated at any time, without changing a line of code. Each of your projects can be mapped differently, affording you plenty of flexibility.
Let’s take a look at how it works.
Mapping Your Activities[](#mapping-your-activities)
----------------------------------------------------
To get started on your custom map, you can either:
* Add mappings one-by-one via our [Dashboard (opens in a new tab)](https://app.climatiq.io)
.
* Import your entire taxonomy to Climatiq either via the `labels` endpoint ([read more here](/docs/api-reference/custom-mappings#custom-mapping-labels)
) or upload via our dashboard, then review suggested mappings provided by Climatiq.
* Upload your taxonomy as a CSV file with Climatiq `activity_id`s already mapped.
Creating a New Single Mapping via the Dashboard[](#creating-a-new-single-mapping-via-the-dashboard)
----------------------------------------------------------------------------------------------------
### Navigate to the Custom Mappings Screen[](#navigate-to-the-custom-mappings-screen)
To create your first mapping, navigate to the Custom Mappings screen in [Climatiq Dashboard (opens in a new tab)](https://app.climatiq.io)
and click on the “Add new mapping" button.
### Input a Mapping Label[](#input-a-mapping-label)
This will add a line to your mapping table. Type the label you would like to use in to the “Activity label” field.
### Await Activity ID Suggestions[](#await-activity-id-suggestions)
As soon as you add it, you may see a suggested Activity ID based on the label that you have chosen for your mapping. You can now accept the suggested activity ID (and save the new mapping), try to refine the suggestion by using the filters below or click one of the links provided to find an Activity ID in our Data Explorer. Once you are happy with the mapping, click "Save changes".
Let's say, for example, that your accounting software has a category called “IT Equipment” and you’d like to automatically map that to an appropriate emission factor without changing anything in your accounting software or associated code. You'd also prefer to map it to an emission factor that comes from the source “EXIOBASE“. You would then write “IT Equipment” into the “activity label” field, select “EXIOBASE“ in the source filter selector and wait for a suggestion. If the suggestion applies to your criteria, then click on “Accept suggestion & save“. Otherwise, follow the links to [Climatiq Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
to find right emission factor for this activity in the, then copy it into the Activity ID field in the Custom Mapping tool.
### Save the Changes[](#save-the-changes)
Click save, and you’ve created your first custom mapping! Note that you might need to wait a minute or two before the changes take effect in the API.
Creating Mappings in Batches[](#creating-mappings-in-batches)
--------------------------------------------------------------
You also have the option to create many mappings at once by uploading a CSV file.
### Navigate to the Custom Mappings Uploader[](#navigate-to-the-custom-mappings-uploader)
Navigate to the Custom Mappings screen in [Climatiq Dashboard (opens in a new tab)](https://app.climatiq.io)
and click on the “Upload mappings" button.
### Prepare your CSV file[](#prepare-your-csv-file)
The CSV file contains two different columns: Activity label and activity ID. **Any row in the file that contains an empty activity ID will get a suggested activity ID in return**. Note that you can also send unmapped taxonomies via the `labels` endpoint ([read more here](/docs/api-reference/custom-mappings#custom-mapping-labels)
)
For example, let's say that you need to create two mappings with activity labels “Hardware“ and “IT Equipment“. You already know an activity ID for the first one but not for the latter one so your CSV file would look like this:
activity_label,activity_idHardware,consumer_goods-type_domestic_appliances_disposablesIT Equipment,
### Upload the CSV File[](#upload-the-csv-file)
Click on the "Select CSV file..." button and choose the file from your computer. If you want to narrow down suggestions for labels that are not mapped to an activity ID, you can choose a source or unit type using the filters provided. In return, the uploader will suggest an activity ID for you with these filters applied. Finally, click on the "Submit" button.
### Review the Unmapped/Suggested Mappings[](#review-the-unmappedsuggested-mappings)
Once the file is processed, you will be redirected to the custom mappings table with the new records in it. The first record will be automatically mapped to the specified activity ID in your file. However, the second one will appear as `Unmapped`. This means that the activity is not yet mapped and not available for estimations when using the API.
If Climatiq was able to find a suggested Activity ID based on the label (“IT Equipment“), the table will give you the choice to accept the suggestion. If it is accepted, the mapping will be saved and the “Unmapped“ status will disappear, meaning that the mapping is ready to use in carbon estimations.
The next step is to review all unmapped records and confirm an activity ID. Click on the edit button and either provide a valid Activity ID or accept the suggested one, as you did in the previous section.
Upload Mapping Labels via the Custom Mappings Labels Endpoint[](#upload-mapping-labels-via-the-custom-mappings-labels-endpoint)
--------------------------------------------------------------------------------------------------------------------------------
Note that you can also send unmapped records via the `labels` endpoint ([read more here](/docs/api-reference/custom-mappings#custom-mapping-labels)
). By doing so, the mappings will be stored as “Unmapped“, you can later navigate to the custom mappings table in the Dashboard and follow the same review process described in the previous section.
Making a query using the Custom Mapping endpoint[](#making-a-query-using-the-custom-mapping-endpoint)
------------------------------------------------------------------------------------------------------
Now that we have an emission factor mapped to a custom label, we can use that label in the [Custom Mapping endpoint](/docs/api-reference/custom-mappings)
to perform emission estimations. For this exercise, we will take as our example “activity” a laptop computer purchased in Germany.
curl --request POST \ --url https://api.climatiq.io/custom-mappings/v1/estimate \ --header 'Authorization: Bearer $CLIMATIQ_API_KEY' \ --data '{ "custom_activity": { "label": "IT Equipment", "data_version": "0.0", "region": "DE" }, "parameters": { "money": 1099, "money_unit": "eur" }}'
And you will get the following response back.
{ "co2e": 233.0979, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Office machinery and computers", "activity_id": "office_equipment-type_office_machinery_computers", "id": "382cc9d8-2380-4dc3-8a61-a85cd6146042", "access_type": "public", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": 2019, "region": "DE", "category": "Office Equipment", "source_lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 233.0979, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 1099.0, "activity_unit": "eur" }, "audit_trail": "selector"}
This response indicates that the purchase resulted in 233.1 kgCO2e of emissions. From now on, every activity defined as "IT Equipment" will be correctly mapped to the appropriate emission factor. If the emission factor is available across different geographies, we can estimate emissions for another region using the same custom mapping.
For instance, if another laptop was bought in the UK for £999, you simply adjust the region code to `GB`, the monetary value to `999`, and the currency to `gbp` to receive an updated estimation.
Summary[](#summary)
--------------------
We’ve shown you how you can map your own custom identifiers to activity IDs, allowing you to set up and maintain a taxonomy of activities without ever needing to change a line of code, or manage mappings in a spreadsheet or other tool.
Please do [get in touch (opens in a new tab)](https://www.climatiq.io/contact-us)
with any issues you encounter or ideas you have for improvements.
[Use Classification Codes](/docs/guides/tutorials/classification-codes "Use Classification Codes")
[Using source\_lca\_activity with Climatiq](/docs/guides/tutorials/lca "Using source_lca_activity with Climatiq")
---
# Using source_lca_activity with Climatiq - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Using source\_lca\_activity with Climatiq
Using source\_lca\_activity with Climatiq
=========================================
**This guide explains how Climatiq integrates Lifecycle Assessment (LCA) from various sources into emission factor data and how to choose an LCA activity for a number of example use cases.**
Each emission factor within the Climatiq database represents an activity or group of activities that gives rise to greenhouse gas emissions. Before adding emission factors to the database and making them available through the API, Climatiq assesses the LCA (Lifecycle Assessment) approach taken by the source. Each emission factor is then labeled to reflect the activities included.
The `source_lca_activity` field within the Climatiq database indicates which of the life cycle stages, or activities within each stage, are covered by the emission factor.
For a general introduction to the lifecycle assessment methodology, see [A Quick Guide to Lifecycle Assessments](/docs/guides/understanding/lca-activity)
.
#### Corporate Reporting[](#corporate-reporting)
For corporate reporting you need to consider the LCA stages in terms of their use for Corporate Reporting in the Greenhouse Gas Protocol (GHGP).
In GHGP the terms “upstream” and “downstream” relate to a company, not a good or service. They are defined by who pays for and / or performs the good or service. In general goods and services paid for by the reporting company are upstream and those paid for by others are downstream. There are 15 scope 3 categories and the first eight (e.g. purchased goods and services and business travel) are upstream from the company and the last 7 (e.g. use of sold products, end of life) are downstream. See [A Quick Guide to Lifecycle Assessments](/docs/guides/understanding/lca-activity)
article for an explanation of how this differs from a product-focused LCA approach.
Choosing a source\_lca\_activity[](#choosing-a-source_lca_activity)
--------------------------------------------------------------------
The first step is to choose the appropriate emission factor for the good or service, represented by the `activity_id`. See the [article here](/docs/guides/understanding/what-is-an-activity-id)
for an explanation of `activity_id`.
When you have picked your `activity_id` (and year, region, and source if applicable) then you can use the [search endpoint](/docs/guides/how-tos/search-refinement)
to find the associated `source_lca_activity` entries.
The next sections explain how Climatiq handles the various different LCA activity information provided by emission factors providers / sources and how the API chooses between `source_lca_activity` when none is specified. After that there are some common use case examples.
The table at the end of this article lists all the main `source_lca_activity` entries and what they mean.
### LCA under Different Sources[](#lca-under-different-sources)
Sources (e.g. UK Government, EPA, ADEME) handle LCA activities differently. Taking a fuel as an example, one source might provide separate emission factors for the activities associated with the fuel and another might combine all activities into one emission factor.
In the first case, the combustion of the fuel might have LCA activity `fuel_combustion`, with another "upstream" emission factor for the extraction, refinement and transportation of the fuel with LCA activity `well_to_tank`.
In the second case a source may provide one emission factor that includes both activities. This activity might have a life-cycle activity called `fuel_upstream-fuel_combustion` that covers both well-to-tank and combustion.
At Climatiq we try to use the same terms as the sources so there may be some differences in `source_lca_activity` labels for emissions factors for similar activities from different sources.
Not all sources specify what sort of LCA activities they consider; these are listed as `unknown`.
### Filtering LCA Activities and defaults[](#filtering-lca-activities-and-defaults)
You can filter on LCA activity in the search endpoint and estimate endpoint. If you don’t explicitly apply filters, Climatiq will return the emission factor with the highest value that matches the query made.
If the query returns emission factors for more than one year then the API will pick the newest one. If there are multiple emission factors from the same year the API will pick the one with the highest value.
To avoid the API from using the newest / highest emission factor you need to provide an explicit filter on the `source_lca_activity` field. You may need to refer to the table below / to the source to see what each `source_lca_activity` represents.
Example reporting use cases[](#example-reporting-use-cases)
------------------------------------------------------------
### Fuel combustion (including travel and transport)[](#fuel-combustion-including-travel-and-transport)
> Use case: You want to report scope 1 emissions from fuel combustion in assets you own or operate, or scope 3 emissions from assets owned or operated by a third party (for scope 3, you may also need to include upstream emissions as well.)
Emissions from the fuel combustion (also known as tailpipe or tank-to-wheel) are, for the majority of emission factors, labeled `source_lca_activity: fuel_combustion` or `source_lca_activity: tank_to_wheel`.
### Upstream emissions from the production of fuel[](#upstream-emissions-from-the-production-of-fuel)
> Use case: You want to report scope 3.3 emissions from the production of fuels burned in assets you own or operate, or complete scope 3 emissions from assets owned or operated by a third party
Emissions from the production of fuels (also known as well-to-tank) are, for the majority of emission factors, labeled `source_lca_activity: well_to_tank`.
### Electricity[](#electricity)
> Use case: You want to report scope 2 emissions from the use of electricity in assets you own or operate
Scope 2 emissions arise from fuel combustion in power plants. Use `source_lca_activity: electricity_generation`.
> Use case: You want to report scope 3 emissions from the use of electricity in assets you own or operate
Scope 3 emissions arise from the production of fuels used in electricity generation and emissions associated with the generation of electricity lost in transmission & distribution.
Some sources (e.g. BEIS) provide three emission factors to cover these. Others use just one or two. Note that for electricity you will (unless you use the Energy Feature) use two `activity_id`s. The relevant combinations of `activity_id` and `source_lca_activity` are as follows for the most popular sources.
| activity\_id | source\_lca\_activity | Source |
| --- | --- | --- |
| [electricity-supply\_grid-source\_supplier\_mix (opens in a new tab)](https://www.climatiq.io/data/activity/electricity-supply_grid-source_supplier_mix) | well\_to\_tank | BEIS, DISER, IEA |
| [electricity-supply\_grid-source\_supplier\_mix\_losses (opens in a new tab)](https://www.climatiq.io/data/activity/electricity-supply_grid-source_supplier_mix_losses) | transmission\_and\_distribution | BEIS, DISER, Government of Canada |
| [electricity-supply\_grid-source\_supplier\_mix\_losses (opens in a new tab)](https://www.climatiq.io/data/activity/electricity-supply_grid-source_supplier_mix_losses) | well\_to\_tank | BEIS |
See the [Energy feature](/docs/api-reference/energy)
and the [guide for Fuel and Energy Related Activities](/docs/guides/understanding/selecting-electricity-efs-scope-3)
for more details.
### Emissions from the purchase (production and transportation of) goods and services[](#emissions-from-the-purchase-production-and-transportation-of-goods-and-services)
> Use case: You want to report scope 3.1 or 3.2 emissions from the purchase of goods and services or capital goods.
Emissions arise from upstream activities in the production of goods and services including primary production (extraction of raw materials, growing crops), refining / processing, manufacturing, packaging and transportation between stages.
For all spend-based emission factors (EXIOBASE, EPA, BEIS) and most other emission factors there is only one `source_lca_activity` for each `activity_id`.
The exceptions are for sources such as CBAM, ecoinvent and for food products. In these cases you will need to read the description (available in Explorer) of the emission factor and pick the one most suited to your case.
List of source\_lca\_activity[](#list-of-source_lca_activity)
--------------------------------------------------------------
The table below sets out the most common `source_lca_activity` field values used in the Climatiq database. It is ordered by the most-used emission factors first (fuel combustion and electricity generation) then in approximate order of LCA stage. Where the definition is specific to a source, the source name is given before the description (e.g. CCF, IPCC, EPA).
The majority (97%) of emission factors relate to the upstream and / or use phases. This is because most emission factors relate to the production of a good or service (upstream) or the combustion of a fuel (use).
The remaining (3%) of emission factors relate to the downstream phase - activities associated with their processing or from their disposal or other end-of-life treatment.
| source\_lca\_activity | Description and (source) |
| --- | --- |
| `unknown` | It is not clear from the source which life cycle activities are included. This is also used for spend-based factors - see the note below. |
| `cradle_to_gate` | Emissions from all activities associated with the manufacturing of a good and its inputs up to the factory gate.
The extraction / processing / transportation of materials and manufacturing. |
| `cradle_to_farm_gate` | Food (e.g. [WRAP (opens in a new tab)](https://www.climatiq.io/data/source/wrap)
): all activities, direct and indirect, associated with production to the point they leave the farm. |
| `cradle_to_processing_gate` | Food (e.g. [WRAP (opens in a new tab)](https://www.climatiq.io/data/source/wrap)
): all activities, direct and indirect, associated with production to the farm gate plus further processing. |
| `cradle_to_shelf` | All activities, direct and indirect, associated with production and transportation to the point of sale on a shop shelf. For spend-based EFs this will include many levels of indirect activities. |
| `cradle_to_grave` | All Upstream, use, and downstream activities |
| `gate_to_grave` | Disposal, recycling or other treatment of the good at the end of its life including transportation to point of disposal. |
| `fuel_combustion` | The combustion of fuel. |
| `biogenic_co2_combustion` | Biogenic CO2 emissions from the combustion of biofuels |
| `use_phase` | [CCF (opens in a new tab)](https://www.climatiq.io/data/source/ccf)
: the use of a CPU in a data center (electricity generation).
[IPCC (opens in a new tab)](https://www.climatiq.io/data/source/ipcc)
: in-field nitrogen losses from fertilizer application.
[EPA (opens in a new tab)](https://www.climatiq.io/data/source/epa)
: vehicle use (fuel combustion).
[UBA (opens in a new tab)](https://www.climatiq.io/data/source/uba)
: district heating |
| `electricity_generation` | Generation of electricity (fuel combustion). |
| `transmission_and_distribution` | The generation of electricity that is lost through transmission and distribution. Also applies to losses of heat, steam and gases. |
| `well_to_tank` | Extraction and refining and transportation of primary fuels before their use |
| `well_to_wheel` | [GLEC (opens in a new tab)](https://www.climatiq.io/data/source/glec)
: Equal to `well_to_tank` plus `tank_to_wheel`. Extraction and refining of primary fuels, transportation, and final combustion in a vehicle. |
| `tank_to_wheel` | [GLEC (opens in a new tab)](https://www.climatiq.io/data/source/glec)
: fuel combustion (in a vehicle). Equivalent to use and fuel\_combustion activities |
| `well_to_propeller` | Well to tank plus tank to propeller (wheel): combustion plus extraction and refining and transportation of primary fuels before their use. |
| `direct` | [CBAM (opens in a new tab)](https://www.climatiq.io/data/source/cbam)
: the manufacturing of a good (and its precursors). |
| `indirect` | [CBAM (opens in a new tab)](https://www.climatiq.io/data/source/cbam)
: electricity used in the manufacturing of a good (and its precursors). |
| `total` | [CBAM (opens in a new tab)](https://www.climatiq.io/data/source/cbam)
: the sum of direct and indirect. |
| `upstream-end_of_life` | [CCF (opens in a new tab)](https://www.climatiq.io/data/source/ccf)
: all activities, direct and indirect, associated with the production, transportation and final disposal or other end-of-life treatment. Does not include use. |
| `end_of_life` | Disposal, recycling or other treatment of the good at the end of its life including transportation to point of disposal. |
| `upstream-use_phase-transport` | [GEMIS (opens in a new tab)](https://www.climatiq.io/data/source/gemis)
: Fuel or electricity: fuel combustion (direct or in electricity generation), well-to-tank of fuels, transmission and distribution losses. |
| `fugitive_release` | \`Fugitive releases of gases listed under the Kyoto Protocol - often refrigerants but also methane and other greenhouse gases. |
| `fugitive_release_non_kyoto` | Fugitive releases of gases not listed under the Kyoto Protocol and not covered by some reporting regulations. |
| `electricity_generation-transmission_and_distribution` | Generation of electricity consumed and lost through transmission and distribution. |
| `upstream` | Mining or production of primary / raw materials / fuels. |
| `carbon_storage-cradle_to_gate` | As for cradle\_to\_gate, with a credit (negative value) for the biogenic CO2 stored as carbon in the product. |
| `upstream-use_phase` | Emissions from combustion / use plus upstream (well to tank) from extraction and refining and transportation of primary fuels before their use. |
| `upstream-fuel_combustion` | Emissions from combustion plus upstream (well to tank) from extraction and refining and transportation of primary fuels before their use. |
| `upstream-electricity_generation` | Generation of electricity (fuel combustion) plus upstream (well to tank) from extraction and refining and transportation of primary fuels before their use. |
| `upstream-electricity_generation-transmission_and_distribution` | Generation of electricity (fuel combustion) plus upstream (well to tank) from extraction and refining and transportation of primary fuels before their use for electricity consumed and lost through transmission and distribution. |
| `electricity_consumption` | [MfE (opens in a new tab)](https://www.climatiq.io/data/source/mfe)
: generation of electricity (used in a vehicle). |
| `well_to_tank-transmission_and_distribution` | Upstream (well to tank) from extraction and refining and transportation of primary fuels used to generate electricity lost in transmission and distribution. |
| `upstream-electricity_consumption` | Generation of electricity (used in a vehicle) plus upstream (well to tank) from extraction and refining and transportation of primary fuels used to generate electricity. |
| `upstream-use_phase-transport-transmission_and_distribution` | Generation of electricity (fuel combustion) plus upstream (well to tank) from extraction and refining and transportation of primary fuels before their use for electricity consumed and lost through transmission and distribution. |
| `electricity_consumption-fuel_combustion` | Generation of electricity (used in a vehicle) plus fuel combustion (in a vehicle). |
| `upstream-transmission_and_distribution` | Upstream fuel production and transmission and distribution of district heating. |
### Spend-based emission factors[](#spend-based-emission-factors)
Spend-based emission factors are produced in a very different way to all other emission factors. They use emissions data from each industry and how much is spent between industries to estimate total emissions from expenditure on a particular industry. As such they include a share of emissions from every industry involved directly or indirectly in the production of a good or service. They are therefore much more comprehensive in their coverage than LCA-based emission factors that will only include significant sources of emissions. The LCA activity may be listed as `unknown` but it is typically functionally equivalent to `cradle_to_gate`.
[Create Custom Mappings](/docs/guides/tutorials/custom-mapping-intro "Create Custom Mappings")
[Calculate Emissions from Freight Shipping](/docs/guides/tutorials/intermodal "Calculate Emissions from Freight Shipping")
---
# Classifications - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Classifications
Classifications ADD-ONADD-ON
============================
Many sources link [emission factors (opens in a new tab)](https://www.climatiq.io/data)
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)](https://unstats.un.org/unsd/classifications/Econ/isic)
):
| Industry Classification code | Primary dataset |
| --- | --- |
| **[ISIC Rev. 4 (opens in a new tab)](https://unstats.un.org/unsd/classifications/Econ/isic)
** | **[GHG Protocol (opens in a new tab)](https://www.climatiq.io/data/explorer?source=GHG+Protocol&unit_type=Money)
**(via ISIC 3.1) |
| **[NACE Rev. 2 (opens in a new tab)](https://ec.europa.eu/eurostat/web/products-manuals-and-guidelines/-/ks-ra-07-015)
** | **[EXIOBASE3 (opens in a new tab)](https://www.climatiq.io/data/explorer?source=EXIOBASE)
** |
| **[Merchant Classification Codes (MCCs) (opens in a new tab)](https://www.citibank.com/tts/solutions/commercial-cards/assets/docs/govt/Merchant-Category-Codes.pdf)
** | **[EXIOBASE3 (opens in a new tab)](https://www.climatiq.io/data/explorer?source=EXIOBASE)
** |
| **[United Nations Standard Products and Services Code (UNSPSC) (opens in a new tab)](https://www.unspsc.org/)
** | **[EXIOBASE3 (opens in a new tab)](https://www.climatiq.io/data/explorer?source=EXIOBASE)
** |
| **[North American Industry Classification System (NAICS) (opens in a new tab)](https://www.naics.com/)
** | **[U.S. Government (EPA) (opens in a new tab)](https://www.climatiq.io/data/source/epa)
** |
For a more in-depth view on how Climatiq works with classification schemes, [view the classification guide](/docs/guides/tutorials/classification-codes)
.
Estimate[](#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)](https://en.wikipedia.org/wiki/International_Standard_Industrial_Classification)
or [NACE (opens in a new tab)](https://en.wikipedia.org/wiki/Statistical_Classification_of_Economic_Activities_in_the_European_Community)
. All requests are performed by sending a POST request to the following endpoint:
https://api.climatiq.io/classifications/v1/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)](https://unstats.un.org/unsd/classifications/Econ/isic)
, 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](/docs/api-reference/classifications#estimate)
for more details on how parameters and units work.
### Request[](#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
✖ Hide child attributes
* * *
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](/docs/api-reference/data-version-endpoint)
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
A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor applies.
* * *
classification.region\_fallbackboolean
Default value: `false`
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
Default value: `false`
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)](/docs/guides/tutorials/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.](/docs/guides/understanding/co2e-calculation)
. 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](/docs/guides/understanding/data-quality)
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](/docs/api-reference/models/parameters)
object
Emission factor parameters. The parameter object changes depending on the EF selected.
curl --request POST \ --url https://api.climatiq.io/classifications/v1/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[](#response)
This endpoint returns an [EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
, which includes the total amount of emissions in `kgCO2e` and the emission factor used to calculate the emissions.
Response parameters
* Estimation_[EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
object_
An object that describes the total amount of co2e and the emission factor used.
{ "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": "f9682106-3615-4d90-b200-89c7b938a256", "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" } ]}
[Procurement](/docs/api-reference/procurement "Procurement")
[Classifications v2 (preview 1)](/docs/api-reference/classifications/classifications-v2-preview1 "Classifications v2 (preview 1)")
---
# Custom Mappings - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Custom Mappings
Custom Mappings ADD-ONADD-ON
============================
Instead of using code to specify emission factors you want to use for your calculations, you can map your own labels to Climatiq activity IDs in the [Climatiq dashboard (opens in a new tab)](https://app.climatiq.io)
, allowing the Climatiq API to recognize whatever values you use to categorize your activities. In the dashboard simply link a custom mapping `label` to an [activity ID](/docs/api-reference/models/selector#using-activity-id)
, and this can then be used in the custom mapping endpoints.
This means you can add and manage how your activities map to emission factors without having to update your code. [View the how-to guide](/docs/guides/tutorials/custom-mapping-intro)
to be taken step-by-step through creating custom mappings and performing queries.
**Data versioning of custom mappings**
We are still working on how to use data versioning within custom mappings to be as convenient as possible. We ask that you use custom mapping endpoints only with data version `0.0` for now. Using another data version may lead to unexpected behavior when we change how data versioning works with custom mappings.
Estimate[](#estimate)
----------------------
POST Calculate total estimated emissions produced for a particular activity in `kgCO2e` using a custom mapping that you have defined under the Custom Mapping tab inside your [Climatiq Dashboard (opens in a new tab)](https://app.climatiq.io/)
.
A custom mapping `label` provides the same flexibility as the ID it maps to. This can happen when multiple emission factors share an [activity ID](/docs/api-reference/models/selector#using-activity-id)
, or because you have mapped the same label to different emission factor ids.
You can provide parameters to select emission factors by filtering using year, region, data source and more as described in our [selector section](/docs/api-reference/models/selector)
. If there are multiple emission factors Climatiq will automatically pick the most conservative one.
https://api.climatiq.io/custom-mappings/v1/estimate
### Request[](#request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* custom\_mappingrequired object
A selector allowing the use of a custom label defined in the custom mapping tab in the [Climatiq Dashboard](http://app.climatiq.io/)
✖ Hide child attributes
* * *
custom\_mapping.labelrequired string
The custom label you have specified in your dashboard.
* * *
custom\_mapping.data\_versionrequired string
The [Data Version](/docs/api-reference/data-version-endpoint)
string for this request. You should use `0.0` currently.
* * *
custom\_mapping.sourcestring
Emission factor data source name.
* * *
custom\_mapping.regionstring
A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor applies.
* * *
custom\_mapping.region\_fallbackboolean
Default value: `false`
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`
* * *
custom\_mapping.year\_fallbackboolean
Default value: `false`
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`
* * *
custom\_mapping.yearinteger
The year in which the emission factor is considered most relevant, according to the source.
* * *
custom\_mapping.source\_lca\_activitystring
The [Life Cycle Assessment (LCA)](/docs/guides/tutorials/lca)
activity to which this factor is associated.
* * *
custom\_mapping.calculation\_methodstring
The calculation method that will be used to calculate the CO2e emission factor. Options are `"ar4"`, `"ar5"`, or `"ar6"`. [Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation)
* * *
custom\_mapping.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](/docs/guides/understanding/data-quality)
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](/docs/api-reference/models/parameters)
Emission factor parameters. The parameter object changes depending on the EF selected.
# In this example, you have already specified "Hotels and accommodation" as a custom mapping in the dashboard# and linked it to an emission factor that use the Money unit.curl --request POST \ --url https://api.climatiq.io/custom-mappings/v1/estimate \ --header 'Authorization: Bearer $CLIMATIQ_API_KEY' \ --data '{ "custom_activity": { "label": "Hotels and accommodation", "data_version": "0.0", "region": "GB" }, "parameters": { "money": 100, "money_unit": "gbp" }}'
### Response[](#response)
You will get an [Estimation](/docs/api-reference/models/estimation#estimation)
back with the CO2e for the given custom mapping, based on the `id` that it is mapped to in the Custom Mapping tool in the [Climatiq Dashboard (opens in a new tab)](http://app.climatiq.io/)
.
{ "co2e": 24.7, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Accommodation services", "activity_id": "accommodation_type_accommodation_services", "id": "de9e8e96-f7c9-4c98-9263-6f1b5a1f40d0", "access_type": "public", "source": "BEIS", "source_dataset": "UK full dataset including conversion factors by SIC code", "year": 2019, "region": "GB", "category": "Accommodation", "source_lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 24.7, "co2e_other": null, "co2": 14.7, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 100.0, "activity_unit": "gbp" }, "audit_trail": "selector"}
### Batch Estimate Endpoint[](#batch-estimate-endpoint)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/custom-mappings/v1/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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
Custom Mapping Labels[](#custom-mapping-labels)
------------------------------------------------
POST Adds new unmapped labels for custom mappings to the project, that the provided API key belongs to.
This will create pending mappings on the project which can be completed in the [Climatiq Dashboard](/docs/guides/tutorials/custom-mapping-intro)
, where suggestions will be provided for automatic mapping.
https://api.climatiq.io/custom-mappings/v1/labels
### Request[](#request-1)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* labelsrequired array of objects
The label used to designate your custom mapping. Does not need to be unique, as you can map the same label to multiple of Climatiq's activities. **unit\_type** and **source** are _optional_ and used as filters for Climatiq to use when suggesting activities to map to your labels, you can change this later in the dashboard.
✖ Hide child attributes
* * *
labels\[x\].labelrequired string
The label used to designate your custom mapping. Does not need to be unique, as you can map the same label to multiple of Climatiq's activities.
* * *
labels\[x\].unit\_typearray of strings
Default value: All sources allowed
The [Climatiq unit types](/docs/api-reference/unit-types)
which are acceptable for automatic mapping suggestions to be selected from.
Default Value
All sources allowed
* * *
labels\[x\].sourcearray of strings
Default value: All sources allowed
The sources which are acceptable for automatic mapping suggestions to be selected from.
Default Value
All sources allowed
* * *
labels\[x\].allow\_duplicatesboolean
Default value: `true`
Set this flag to `false` to avoid creating duplicates of mappings.
Default Value
`true`
* data\_versionrequired string
Default value: 0.0
The required [Data Version](/docs/api-reference/data-version-endpoint)
string within which activities will be sought to match the labels.
Default Value
0.0
curl --request POST \--url https://api.climatiq.io/custom-mappings/v1/labels \--header 'Authorization: Bearer $CLIMATIQ_API_KEY' \--data '{ "data_version": "0.0", "labels": [ { "label": "hotel room", "source": ["BEIS"] }, { "label": "Electricity generation" } ]}'
### Response[](#response-1)
The response will show an array of the newly created pending mappings, including a suggested activity\_id **if** one is found. These mappings are not ready to be used until a user with access to this project visits the Climatiq dashboard and completes the mapping. Any ignored mappings (due to use of the `allow_duplicates` field) will not be included.
Response parameters
* labelstring
The label used to designate this custom mapping.
* activity\_idstring
The `activity_id` that will be suggested in the custom mappings dashboard, if a suitable one has been found.
* idstring
The unique ID for this particular mapping.
[ { "label": "hotel", "activity_id": "accommodation_type_hotel_room", "id": "35354707520" }]
[Cloud Computing](/docs/api-reference/computing "Cloud Computing")
[Travel (preview)](/docs/api-reference/travel "Travel (preview)")
---
# Intermodal Freight Transportation v2 - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Calculate Emissions from Freight Shipping
Intermodal Freight Transportation v2
====================================
**Climatiq allows you to calculate the carbon emissions for shipping freight around the world using multiple modes of transport (intermodal) such as by sea, air, road or rail. This guide will show you how to use the intermodal freight endpoint and explain some concepts. For more detailed documentation, go to the [API reference](/docs/api-reference/intermodal-freight)
.**
⚠️
**Subscription plan required**
This is a paid feature. Please see our [pricing page](https://www.climatiq.io/pricing)
for more details.
Introduction[](#introduction)
------------------------------
The endpoint automatically:
* Selects emission factors for the regions, vehicles and load you are transporting from the GLEC framework.
* Calculates the distance between the start and end location of the shipment.
* Finds the port, railway terminal or airport that is closest to your locations, for transfer between different transport modes.
All emission factors used are from the [Global Logistics Emissions Council (GLEC) framework (opens in a new tab)](https://www.climatiq.io/data/source/glec)
except for grid electricity factors for powering electric vehicles which come from [International Energy Agency(IEA) (opens in a new tab)](https://www.climatiq.io/data/source/iea)
.
To estimate rail leg distances and provide names of railway logistics hubs, we utilize data from [OpenStreetMap (opens in a new tab)](https://www.openstreetmap.org/copyright)
, which we obtain under the [Open Database License (opens in a new tab)](https://opendatacommons.org/licenses/odbl/)
.
Current Limitations[](#current-limitations)
--------------------------------------------
The intermodal endpoint has a few limitations:
* You are currently allowed only three legs per API call by default. [Contact Climatiq (opens in a new tab)](https://www.climatiq.io/contact-us)
to get this limit raised.
* Rail transportation estimates are lower quality outside of Europe. The GLEC framework does not provide as granular emission factors, and we do not have actual railroad paths for all regions outside of Europe.
With that out of the way, let's dive into what a request to the intermodal endpoint could look like.
Example Request[](#example-request)
------------------------------------
curl --request POST \--url https://api.climatiq.io/freight/v2/intermodal \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "route": [ { "location": { "query": "Hamburg" } }, { "transport_mode": "road" }, { "transport_mode": "sea" }, { "transport_mode": "road" }, { "location": { "query": "Las Vegas" } } ], "cargo": { "weight": 10, "weight_unit": "t" }}'
That will take cargo from Hamburg to Las Vegas via sea shipping, finding road routes to the nearest harbor to each city first.
We won't look in-depth at the response in this guide, but it will include, among other things, the distance and CO2-equivalents for the entire trip, and each leg separately. You can see the full response in the [API reference documentation](/docs/api-reference/intermodal-freight#response)
.
Now, let's take a closer look at what a request can contain. The full details are available in the [API reference](/docs/api-reference/intermodal-freight#request)
, but we'll also look at it a bit here. The request contains `cargo` which describes the cargo being shipped, and a `route` which is the path the cargo is shipped.
Route[](#route)
----------------
A route consists of two or more locations, and legs between these locations. It must start and end with a location, and there must be a leg between each location.
This is an example of the structure of a valid route:
In some cases (such as the example above) you are allowed to omit some locations and rely on automatic routing. See the section on [automatic routing](/docs/guides/tutorials/intermodal#automatic-routing)
below for more details.
For now, let's take a quick look at legs and locations before diving into some more complex topics.
### Leg[](#leg)
Each route has one or more legs. A leg is a transition between two locations. For a leg you can specify the `transport_mode` to be `air`, `sea`, `road` or `rail`. You may also specify details of the leg such as the vehicle type. See the [API reference](/docs/api-reference/intermodal-freight#route-leg)
for more details of exactly what a leg can contain.
### Location[](#location)
A trip always has two or more locations. Locations contain two things - the `location` object that explains how to actually find the location, and a `location_options` [Location Options](/docs/api-reference/intermodal-freight#location-options)
object that tells Climatiq how to use the location, e.g. for [automatic location correction](/docs/guides/tutorials/intermodal#automatic-location-correction)
, or configuring logistics hubs. This `location` can be specified via free-text query, coordinates, [and more](/docs/api-reference/intermodal-freight#location)
.
Advanced Concepts[](#advanced-concepts)
----------------------------------------
You now know the basic building blocks of the intermodal freight endpoint, but there are a few advanced concepts that might be nice to know about.
### Transition Points[](#transition-points)
Some types of transport have fixed start and end points, such as air travel that must be from airport to airport or rail transport that must be from railway station to railway station.
The general term Climatiq uses for airports, railway stations and sea ports are "transition points". Transportation modes that require transition points are called "fixed transition point" A leg that is between two fixed transition points, such as a rail, sea or air leg is called a "fixed transition point leg"
### Automatic Routing[](#automatic-routing)
In some cases when traveling via [fixed-transition point transport modes](/docs/guides/tutorials/intermodal#transition-points)
, you may omit some locations and rely on Climatiq doing automatic routing for you. As Climatiq has a list of transition points for each of these transport modes, it can automatically select the closest location for these queries.
As an example, the below route expresses the route: "I want to ship this from Hamburg to Miami over sea, using road to connect to the closest ports"
{ "route": [ { "location": { "query": "Hamburg" } }, { "transport_mode": "road" }, { "transport_mode": "sea" }, { "transport_mode": "road" }, { "location": { "query": "Miami" } } ]}
Locations can be omitted on either end of a sea, air or rail journey if the following criteria are met:
1. The fixed-transition point journey has a `road` leg before or after
2. There is a location immediately before/after that road leg
### Automatic Location Correction[](#automatic-location-correction)
If a location is adjacent to a fixed-transition point leg, Climatiq automatically makes a correction to the proper port, airport or railway station.
This means that if you send the following route in a request:
{ "route": [ { "location": { "query": "Amsterdam" } }, { "transport_mode": "sea" }, { "location": { "query": "Miami" } } ]}
Climatiq will correctly route between the Amsterdam and the Miami harbor, even though the Location `Amsterdam` might actually mean the city center, and not the Amsterdam harbor. This is because Climatiq will automatically adjust a location _slightly_ if it needs it to match with a transition point needed for an adjacent leg. The maximum distance it will correct is called the `tolerance_km` - which is the tolerance for how precise your location is.
However, if the distance to the fixed-transition point is too large, Climatiq will not automatically correct the location. As an example, if you put in the following route
{ "route": [ { "location": { "query": "New York" } }, { "transport_mode": "air" }, { "location": { "query": "Copenhagen" } } ]}
You will get an error like this:
{ "error": "bad_request", "error_code": "invalid_input", "message": "Location 'New York, NY, United States' was not close enough to the closest transition point for the air leg. Closest transition point is: 'Newark Liberty International Airport(40.692501,-74.168701)'. Distance between the points is 13.839174000000002km"}
This is because the closest airport is farther away than `tolerance_km` and there are two ways to interpret your request:
1. "I want this flown out of the nearest airport from New York"
2. "I have this in the center of New York, and I need it driven out to the airport, and then flown"
Climatiq will choose the first option, if the transition point and your location are less than `tolerance_km` away from each other. Otherwise, you will have to specify which of the two behaviors you're looking for.
* If you want the first option you can set the `tolerance_km` on the [Location Options](/docs/api-reference/intermodal-freight#location-options)
object, to tell how many kilometers away from your specified location to seek for a fixed-transition point location.
* If you want the second option, you can add a `road` leg between the first location and the `air` leg.
You may also disable automatic location correction by setting the flag `override_transition` on the [Location Options](/docs/api-reference/intermodal-freight#location-options)
object to `true`, informing Climatiq not to attempt to look for a nearby fixed transition point, and assume that the location you have specified _is_ a transition point.
The way this routing is built up allows you to do some rather powerful things, which we'll see in Examples below.
### Examples[](#examples)
Here are some examples of routes using automatic routing and location tolerances. Let's take the base route of someone shipping goods from Berlin to Miami over sea.
As Berlin doesn't have a seaport, we'll need to specify a road leg to the nearest port, like this:
{ "route": [ { "location": { "query": "Berlin" } }, { "transport_mode": "road" }, { "transport_mode": "sea" }, { "location": { "query": "Miami" } } ]}
This will route from Berlin to the nearest port, which is in Poland.
But perhaps we know that we're actually shipping out from a harbor close to Hanover, in which case we could create the following route, which will route from Berlin to a harbor close to Hanover. Due to the `tolerance_km` being set, the location Hanover will actually find the closest harbor to Hanover within 200km. The route will not necessarily go through Hanover itself.
{ "route": [ { "location": { "query": "Berlin" } }, { "transport_mode": "road" }, { "location": { "query": "Hanover" }, "location_options": { "tolerance_km": 200 } }, { "transport_mode": "sea" }, { "location": { "query": "Miami" } } ]}
If you know that you're actually going _through_ Hanover - as perhaps your goods are being repackaged there, your route could look like this.
{ "route": [ { "location": { "query": "Berlin" } }, { "transport_mode": "road" }, { "location": { "query": "Hanover" } }, { "transport_mode": "road" }, { "transport_mode": "sea" }, { "location": { "query": "Miami" } } ]}
If you have are using a transition point that we don't know about, because you've built a temporary dock for a construction project in Southend-on-Sea (which doesn't have a port) and you're bringing in small barges from Rotterdam:
{ "route": [ { "location": { "query": "Rotterdam" } }, { "transport_mode": "sea", "leg_details": { "vessel_type": "bulk_carrier", "tonnage": "lt_10dwkt", "fuel_source": "hfo" } }, { "location": { "query": "Southend-on-Sea" }, "location_options": { "override_transition": true } } ]}
### Refrigerated Cargo[](#refrigerated-cargo)
If you are shipping cargo that needs to be refrigerated, you can pass in the `refrigerated` parameter in the [request](/docs/api-reference/intermodal-freight#request)
`cargo` object. If you do this you will get the emissions for a supply chain where the cargo is kept refrigerated during the entire process.
See the [methodology guide](/docs/guides/understanding/freightv2-ISO14083#refrigerated-cargo)
for an explanation of the effect this parameter has on the calculations performed.
There are a few limitations when dealing with refrigerated cargo:
* For road transport in North America, you cannot specify any `leg_details`.
* For sea transportation, the only `vessel_type`s you can use are `container` and `refrigerated_bulk`.
If you try to perform either of these actions, you will get an error.
[Using source\_lca\_activity with Climatiq](/docs/guides/tutorials/lca "Using source_lca_activity with Climatiq")
[Calculate Emissions from Freight Shipping (v1)](/docs/guides/tutorials/intermodal/intermodal-v1 "Calculate Emissions from Freight Shipping (v1)")
---
# Intermodal Freight Transportation V1 - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
[Calculate Emissions from Freight Shipping](/docs/guides/tutorials/intermodal)
Calculate Emissions from Freight Shipping (v1)
Intermodal Freight Transportation V1
====================================
🚫
**Newer version available**
You are reading documentation for an older version of this feature. We recommend you view the documentation for the latest version of this feature, which is available [here](/docs/guides/tutorials/intermodal)
.
This version of the feature will be removed: December 2024
**Climatiq allows you to calculate the carbon emissions for shipping freight around the world using multiple modes of transport (intermodal) such as by sea, air, road or rail. This guide will show you how to use the intermodal freight endpoint and explain some concepts. For more detailed documentation, go to the [API reference](/docs/api-reference/intermodal-freight/intermodal-freight-v1)
.**
⚠️
**Subscription plan required**
This is a paid feature. Please see our [pricing page](https://www.climatiq.io/pricing)
for more details.
Introduction[](#introduction)
------------------------------
The endpoint automatically:
* Selects emission factors for the regions, vehicles and load you are transporting from the GLEC framework.
* Calculates the distance between the start and end location of the shipment.
* Finds the port, railway terminal or airport that is closest to your locations, for transfer between different transport modes.
All emission factors used are from the [Global Logistics Emissions Council(GLEC) framework (opens in a new tab)](https://www.smartfreightcentre.org/en/how-to-implement-items/what-is-glec-framework/58/)
.
To estimate rail leg distances and provide names of railway logistics hubs, we utilize data from [OpenStreetMap (opens in a new tab)](https://www.openstreetmap.org/copyright)
, which we obtain under the [Open Database License (opens in a new tab)](https://opendatacommons.org/licenses/odbl/)
.
If you prefer a video introduction, here is a 15 minute quickstart guide:
Current Limitations[](#current-limitations)
--------------------------------------------
The intermodal endpoint has a few limitations:
* You are currently allowed only three legs per API call by default. [Contact Climatiq (opens in a new tab)](https://www.climatiq.io/contact-us)
to get this limit raised.
* Rail transportation estimates are lower quality outside of Europe. The GLEC framework does not provide as granular emission factors, and we do not have actual railroad paths for all regions outside of Europe.
With that out of the way, let's dive into what a request to the intermodal endpoint could look like.
Example Request[](#example-request)
------------------------------------
curl --request POST \--url https://api.climatiq.io/freight/v1/intermodal \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "route": [ { "location": { "query": "Hamburg" } }, { "transport_mode": "road" }, { "transport_mode": "sea" }, { "transport_mode": "road" }, { "location": { "query": "Las Vegas" } } ], "cargo": { "weight": 10, "weight_unit": "t" }}'
That will take cargo from Hamburg to Las Vegas via sea shipping, finding road routes to the nearest harbor to each city first.
We won't look in-depth at the response in this guide, but it will include, among other things, the distance and CO2-equivalents for the entire trip, and each leg separately. You can see the full response in the [API reference documentation](/docs/api-reference/intermodal-freight#response)
.
Now, let's take a closer look at what a request can contain. The full details are available in the [API reference](/docs/api-reference/intermodal-freight#request)
, but we'll also look at it a bit here. The request contains `cargo` which is just a [Weight](/docs/api-reference/models/parameters#weight)
unit type, representing the weight of the cargo. It also contains a route, which is the path the cargo is shipped.
Route[](#route)
----------------
A route consists of two or more locations, and legs between these locations. It must start and end with a location, and there must be a leg between each location.
This is an example of the structure of a valid route:
In some cases (such as the example above) you are allowed to omit some locations and rely on automatic routing. See the section on automatic routing below for more details.
For now, let's take a quick look at legs and locations before diving into some more complex topics.
### Leg[](#leg)
Each route has one or more legs. A leg is a transition between two locations. For a leg you can specify the `transport_mode` to be `air`, `sea`, `road` or `rail`. You may also specify details of the leg such as the vehicle type. See the [API reference](/docs/api-reference/intermodal-freight#route-leg)
for more details of exactly what a leg can contain.
### Location[](#location)
A trip always has two or more locations. Locations contain two things - the `location` object that explains how to actually find the location, and a `location_options` [Location Options](/docs/api-reference/intermodal-freight#location-options)
object that tells Climatiq how to use the location, e.g. for [automatic location correction](/docs/guides/tutorials/intermodal#automatic-location-correction)
. This `location` can be specified via free-text query, coordinates, [and more](/docs/api-reference/intermodal-freight#location)
.
Advanced Concepts[](#advanced-concepts)
----------------------------------------
You know now the basic building blocks of the intermodal freight endpoint, but there are a few advanced concepts that might be nice to know about.
### Transition Points[](#transition-points)
Some types of transport have fixed start and end points, such as air travel that must be from airport to airport or rail transport that must be from railway station to railway station.
The general term Climatiq uses for airports, railway stations and sea ports are "transition points". Transportation modes that have transition points are called "fixed transition point" A leg that is between two fixed transition points, such as a rail, sea or air leg is called a "fixed transition point leg"
### Automatic Routing[](#automatic-routing)
In some cases when traveling via [fixed-transition point transport modes](/docs/guides/tutorials/intermodal#transition-points)
, you may omit some locations and rely on Climatiq doing automatic routing for you. As Climatiq has a list of transition points for each of these transport modes, it can automatically select the closest location for these queries.
As an example, the below route expresses the route: "I want to ship this from Hamburg to Miami over sea, using road to connect to the closest ports"
{ "route": [ { "location": { "query": "Hamburg" } }, { "transport_mode": "road" }, { "transport_mode": "sea" }, { "transport_mode": "road" }, { "location": { "query": "Miami" } } ]}
Locations can be omitted on either end of a sea, air or rail journey if the following criteria are met:
1. The fixed-transition point journey has a `road` leg before or after
2. There is a location immediately before/after that road leg
### Automatic Location Correction[](#automatic-location-correction)
If a location is adjacent to a fixed-transition point leg, Climatiq automatically makes a correction to the proper port, airport or railway station.
This means that if you send the following route in a request:
{ "route": [ { "location": { "query": "Amsterdam" } }, { "transport_mode": "sea" }, { "location": { "query": "Miami" } } ]}
Climatiq will correctly route between the Amsterdam and the Miami harbor, even though the Location `Amsterdam` might actually mean the city center, and not the Amsterdam harbor. This is because Climatiq will automatically adjust a location _slightly_ if it needs it to match with a transition point needed for an adjacent leg. The maximum distance it will correct is called the `tolerance_km` - which is the tolerance for how precise your location is.
However, if the distance to the fixed-transition point is too large, Climatiq will not automatically correct the location. As an example, if you put in the following route
{ "route": [ { "location": { "query": "New York" } }, { "transport_mode": "air" }, { "location": { "query": "Copenhagen" } } ]}
You will get an error like this:
{ "error": "bad_request", "error_code": "invalid_input", "message": "Location 'New York, NY, United States' was not close enough to the closest transition point for the air leg. Closest transition point is: 'Newark Liberty International Airport(40.692501,-74.168701)'. Distance between the points is 13.839174000000002km"}
This is because the closest airport is farther away than `tolerance_km` and there are two ways to interpret your request:
1. "I want this flown out of the nearest airport from New York"
2. "I have this in the center of New York, and I need it driven out to the airport, and then flown"
Climatiq will choose the first option, if the transition point and your location are less than `tolerance_km` away from each other. Otherwise, you will have to specify which of the two behaviors you're looking for.
* If you want the first option you can set the `tolerance_km` on the [Location Options](/docs/api-reference/intermodal-freight#location-options)
object, to tell how many kilometers away from your specified location to seek for a fixed-transition point location.
* If you want the second option, you can add a `road` leg between the first location and the `air` leg.
You may also disable automatic location correction by setting the flag `override_transition` on the [Location Options](/docs/api-reference/intermodal-freight#location-options)
object to `true`, informing Climatiq not to attempt to look for a nearby fixed transition point, and assume that the location you have specified _is_ a transition point.
The way this routing is built up allows you to do some rather powerful things, which we'll see in Examples below.
### Examples[](#examples)
Here are some examples of routes using automatic routing and location tolerances. Let's take the base route of someone shipping goods from Berlin to Miami over sea.
As Berlin doesn't have a seaport, we'll need to specify a road leg to the nearest port, like this:
{ "route": [ { "location": { "query": "Berlin" } }, { "transport_mode": "road" }, { "transport_mode": "sea" }, { "location": { "query": "Miami" } } ]}
This will route from Berlin to the nearest port, which is in Poland.
But perhaps we know that we're actually shipping out from a harbor close to Hanover, in which case we could create the following route, which will route from Berlin to a harbor close to Hanover. Due to the `tolerance_km` being set, the location Hanover will actually find the closest harbor to Hanover within 200km. The route will not necessarily go through Hanover itself.
{ "route": [ { "location": { "query": "Berlin" } }, { "transport_mode": "road" }, { "location": { "query": "Hanover" }, "location_options": { "tolerance_km": 200 } }, { "transport_mode": "sea" }, { "location": { "query": "Miami" } } ]}
If you know that you're actually going _through_ Hanover - as perhaps your goods are being repackaged there, your route could look like this.
{ "route": [ { "location": { "query": "Berlin" } }, { "transport_mode": "road" }, { "location": { "query": "Hanover" } }, { "transport_mode": "road" }, { "transport_mode": "sea" }, { "location": { "query": "Miami" } } ]}
If you have are using a transition point that we don't know about, because you've built a temporary dock for a construction project in Southend-on-Sea (which doesn't have a port) and you're bringing in small barges from Rotterdam:
{ "route": [ { "location": { "query": "Rotterdam" } }, { "transport_mode": "sea", "leg_details": { "vessel_type": "bulk_carrier", "tonnage": "lt_10dwkt", "fuel_source": "hfo" } }, { "location": { "query": "Southend-on-Sea" }, "location_options": { "override_transition": true } } ]}
[Calculate Emissions from Freight Shipping](/docs/guides/tutorials/intermodal "Calculate Emissions from Freight Shipping")
[Microsoft Excel Add-In](/docs/guides/tutorials/excel-addin "Microsoft Excel Add-In")
---
# CBAM - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
CBAM (preview)
CBAM 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 three months. Read more about API versioning at Climatiq [here](/docs/guides/understanding/api-versioning)
.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](https://www.climatiq.io/contact-us)
.
The [Carbon Border Adjustment Mechanism (CBAM) (opens in a new tab)](https://taxation-customs.ec.europa.eu/carbon-border-adjustment-mechanism_en)
has been introduced by the European Union (EU) to promote lower carbon production in countries outside of the EU. It places requirements on importers of certain goods (currently Iron & Steel, Aluminum, Cement, Fertilizer, Electricity and Hydrogen) to report emissions from their production and ultimately pay a tax on those emissions. Starting in 2026, companies will be required to purchase certificates corresponding to the total emissions from their imported goods in these categories.
Climatiq's CBAM feature uses benchmark emission factors published by the EU that may be used for reporting purposes where estimates are permitted. These include direct, indirect and total emissions for the countries that, together, produce more than 90% of EU imports. Where there is no EF for the combination of good and region, the [EU default "Rest of World" EF is applied (opens in a new tab)](https://taxation-customs.ec.europa.eu/carbon-border-adjustment-mechanism_en#guidance)
. The default factors may also be obtained directly by using `"ROW"` as the region. Currently, the CBAM emission factors cover just those published by the EU for Iron & Steel, Aluminum, Cement and Fertilizer.
The goods covered by CBAM regulations are defined by specific [Combined Nomenclature (opens in a new tab)](https://taxation-customs.ec.europa.eu/customs-4/calculation-customs-duties/customs-tariff/combined-nomenclature_en)
(CN) codes. The definitive list of goods is given on the [CBAM website in Annex 1 to the Regulation. (opens in a new tab)](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=uriserv%3AOJ.L_.2023.130.01.0052.01.ENG&toc=OJ%3AL%3A2023%3A130%3ATOC)
Note that the official CBAM guidance is subject to review and revision by the EU and users are responsible for ensuring they comply with the latest guidance.
Estimate[](#estimate)
----------------------
POST Calculate total estimated emissions produced for a particular [Combined Nomenclature (opens in a new tab)](https://taxation-customs.ec.europa.eu/customs-4/calculation-customs-duties/customs-tariff/combined-nomenclature_en)
(CN) code, for use with CBAM reporting.
https://preview.api.climatiq.io/cbam/v1-preview1/estimate
This endpoint lets you specify a CN code and have Climatiq automatically select the appropriate emission factor.
CN codes have to follow the same format as the CBAM regulations to be accepted by the endpoint. The format is one of the following - note the spaces between sets of digits.
* 4 digits: 7309
* 6 digits: 7318 15
* 8 digits: 7318 24 00
The string of digits also has to match the string in the CBAM regulations exactly - there is no hierarchy or fall back e.g. “7309 14 00” will not be converted into “7309”.
### Request[](#request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* cn\_coderequired string
The combined nomenclature code for the imported goods.
* production\_regionrequired string
A [region code](/docs/api-reference/regions#region-code)
describing the region the goods were produced in. If you specify `"ROW"` then this will return the EU default factors.
* weightrequired float
The weight of the imported goods in the defined unit
* weight\_unitstring
Default value: `kg`
Unit of weight. One of `g`, `kg`, `t` (metric ton), `lb`, `ton` (US short ton)
Default Value
`kg`
curl --request POST \ --url https://preview.api.climatiq.io/cbam/v1-preview1/estimate \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "cn_code": "7206 10 00", "production_region": "CN", "weight": 100, "weight_unit": "t"}'
### Response[](#response)
This endpoint returns an object with several [EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
, which includes the total amount of emissions in `kgCO2e` and the emission factor used to calculate the emissions.
Response parameters
* co2efloat
The total greenhouse gas emissions associated with the imported goods, expressed in the unit listed in `co2e_unit`
* co2e\_unitstring
The unit in which the `co2e` field is expressed. Currently, this value is always "kg"
* co2e\_calculation\_methodstring
Which calculation methodology that was used for the calculation. The value of this is either `"ipcc_ar4_gwp100"`, `"ipcc_ar5_gwp100"`, `"ipcc_ar6_gwp100"` or `"ipcc_mixed_gwp100"`. [Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation)
* estimated\_costs\_eurfloat
Estimated cost in euros of buying carbon certificates for emissions equivalent to `co2e`, based on the average 2023 certificate cost of 84 euros per tonne.
* direct\_emissions[EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
An object that represents the estimated direct emissions occurred during the production of the imported goods
* indirect\_emissions[EstimationWithSourceTrail](/docs/api-reference/models/estimation#estimationwithsourcetrail)
An object that represents the estimated indirect emissions occurred during the production of the imported goods
* noticesarray of [Notices](/docs/api-reference/cbam#notice)
Any notices related to the calculation.
{ "co2e": 206000, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "estimated_costs_eur": 17304, "direct_emissions": { "co2e": 183000, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Iron non-alloy steel - primary - ingots", "activity_id": "metals-type_iron_non_alloy_steel_primary_ingots", "id": "969d9d23-bec0-4c5f-9727-1ca6a0db7505", "access_type": "public", "source": "CBAM", "source_dataset": "Emission intensities at country level", "year": 2023, "region": "CN", "category": "Metals", "source_lca_activity": "direct", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 183000, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 100000, "activity_unit": "kg" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Iron non-alloy steel - primary - ingots", "source": "CBAM", "source_dataset": "Emission intensities at country level", "year": "2023", "region": "CN", "region_name": "China" } ] }, "indirect_emissions": { "co2e": 23000, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Iron non-alloy steel - primary - ingots", "activity_id": "metals-type_iron_non_alloy_steel_primary_ingots", "id": "46f63b74-63fb-4a52-8fea-436a322893b2", "access_type": "public", "source": "CBAM", "source_dataset": "Emission intensities at country level", "year": 2023, "region": "CN", "category": "Metals", "source_lca_activity": "indirect", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 23000, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 100000, "activity_unit": "kg" }, "audit_trail": "enabled", "source_trail": [ { "data_category": "emission_factor", "name": "Iron non-alloy steel - primary - ingots", "source": "CBAM", "source_dataset": "Emission intensities at country level", "year": "2023", "region": "CN", "region_name": "China" } ] }, "notices": []}
### Notice[](#notice)
The `notices` array can contain objects like these:
| Notice attributes | Type | Description |
| --- | --- | --- |
| **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 machine-readable categorization of the notice to allow automatic handling. |
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 value | description |
| --- | --- |
| `region_fallback` | No specific emission factors were found for the combination of product and imported region. A wider geographic emission factor was used instead. |
[Energy v1 (preview 1)](/docs/api-reference/energy/energy-v1-preview1 "Energy v1 (preview 1)")
[Product Carbon Footprint (preview)](/docs/api-reference/pcf "Product Carbon Footprint (preview)")
---
# Guide to the Google Sheets Extension - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Google Sheets Extension
Guide to the Google Sheets Extension
====================================
**Utilize Climatiq-specific extension for Google Sheets to seamlessly convert your business activity data into carbon estimates across various activities, such as travel, energy usage, and fuel consumption.**
Overview[](#overview)
----------------------
Climatiq’s Google Sheets extension transforms your spreadsheets into a powerful environmental impact assessment tool. No coding is required, allowing you to quickly create proofs of concept and collaborate with your team for feedback before fully integrating Climatiq’s API or developing advanced features. The Add-In lets you visualize results directly in Excel and share detailed emission reports, streamlining approval for sustainability projects with reliable data.
Since this tool provides a simplified version of our API endpoints, we recommend reviewing our documentation or using the guided Postman collection if you are interested in accessing the full capabilities of the API.
Getting Started[](#getting-started)
------------------------------------
Access to Climatiq's API generally requires a commercial subscription. However, for this Extension, we offer a free starter plan that includes up to 500 emission estimations per month, granting access to all advanced emission calculations, e.g. the emission estimations for travel, freight, energy and the Autopilot. Without this plan or a commercial subscription, functionality will be limited to basic estimations, i.e. [General Estimates](/docs/guides/tutorials/google-sheets-extension#general-emission)
and [General Search](/docs/guides/tutorials/google-sheets-extension#search-emission-factors)
. You can sign up for the starter plan [here (opens in a new tab)](https://share.hsforms.com/1q7M2lfmvTWG1jos1q8tUnQbu68c)
. If you anticipate commercial usage or usage beyond the free starter plan limit, please [reach out to our team (opens in a new tab)](https://www.climatiq.io/contact-us)
.
### Installation of the extension[](#installation-of-the-extension)
You can add the extension to Google Sheets by installing it via the [Google Marketplace (opens in a new tab)](https://workspace.google.com/marketplace/app/climatiq_carbon_calculations_for_google/838336080005)
. Once installed, it will be come available via the "Extension" menu item in the Google Sheets menu bar.
### Setting the API key[](#setting-the-api-key)
To be able to use the formulas, you will need to set an API key to be used by the extension when calling Climatiq's API. You can get your API key by following [these steps](/docs/guides/how-tos/getting-api-key)
. Once you've obtained the key, you set it via the Extension menu (Extension > Climatiq > Set API key) in Google Sheets and you are ready to go.
The API key will be stored permanently for this specific sheet and other users using this file will also be able to make use of the formulas. This also means that you will have to set the key once for every new Google sheet in which you'd want to use this integration.
Support and Feedback[](#support-and-feedback)
----------------------------------------------
In case of questions, please reach out to the Climatiq team via the website chat or the [support form (opens in a new tab)](https://www.climatiq.io/support)
. We also appreciate any feedback being shared through these channels.
General Concepts and Notices[](#general-concepts-and-notices)
--------------------------------------------------------------
To get the most out of the extension, it's important to familiarize yourself with the following concepts.
### "ShowDetails" Flag[](#showdetails-flag)
For all Estimation and Autopilot functions, you can choose whether to receive additional calculation details or just the estimated CO2e value in the response. Refer to the documentation for each [formula](/docs/guides/tutorials/google-sheets-extension#formulas)
to see which details are available. The additional details will be stored in the cells following the one containing the function.
### Optional Parameters[](#optional-parameters)
Typically not all parameters are required when using the formulas. The documentation indicates which ones are required and which ones are optional. In case no value should be used for the optional parameters, please simply leave them empty, e.g. `Climatiq_Calculate_Travel_Air(start, end, flightclass)` as `Climatiq_Calculate_Travel_Air("BER", "JFK")`. 
### Error Handling[](#error-handling)
In addition to common errors, formulas will return specific errors from the Climatiq API if an input is incorrect, or if the provided API key is invalid, or a suitable emission factor cannot be found by the API.
### Populate Header Rows[](#populate-header-rows)
Many of the formulas will retrieve results across multiple cells, especially when the "showDetails" flag is being used. To know which different values are being retrieved and to automatically populate the headers for the result columns, there is a collection of dedicated formulas available for this. For every Calculate and Autopilot formula, you can simply add `_Headers` to the original formula name. Additionally, you can indicate, whether the detail column headers should also be populated. A few examples: `=Climatiq_Autopilot_Headers(TRUE)`, `=Climatiq_Calculate_Travel_Air_Headers()` and `=Climatiq_Calculate_IntermodalFreightTransport_Headers(TRUE)`
### API Consumption and Recalculation of Results[](#api-consumption-and-recalculation-of-results)
By default, Google Sheets will re-calculate the results for formulas eeverytime an input changes or the file is reloaded. Every re-calculation will also count as a call to the Climatiq API. To avoid overconsumption of your subscribed API calls, it is recommended to copy-paste the values of the calculations into the cells as soon as the calculations are complete. To do this, you should select the cells with the calculation results, copy them and paste them back into these cells via Edit > Paste Special > Values only.
### Documentation within the Extension[](#documentation-within-the-extension)
To see an overview of the available formulas in a sidebar within Google Sheets, you can open the documentation via the Extension menu (Extension > Climatiq > Show documentation).
### Access to all functionalities[](#access-to-all-functionalities)
By default, when signing up for the Climatiq API, the initial access only covers the usage of the general estimation and search capabilities. For any advanced calculations, e.g. emission estimations for air travel, additional access needs to be granted for your API key. Otherwise the following error will be shown when trying to make use of an advanced features, that has not yet been enabled for your account:
`Your authentication is valid, but you do not have access to this feature.`
To enable these advanced features, you can sign up to a free starter plan, which covers up to 500 emission estimations monthly across advanced emission calculations. You can sign up for this plan [here (opens in a new tab)](https://share.hsforms.com/1q7M2lfmvTWG1jos1q8tUnQbu68c)
. And in case you are interested in large-scale usage of the integration, please [reach out to our team (opens in a new tab)](https://www.climatiq.io/contact-us)
.
Formulas[](#formulas)
----------------------
There are three sets of formulas available:
* **Estimations:** Easily calculate the emissions for different kinds of business activities, e.g. travel, shipping and energy usage based on detailed methodologies
* **Autopilot:** Leverage Climatiq's [Autopilot](/docs/api-reference/autopilot)
to automate spend- and activity-based emission estimates
* **Search:** Look up emission factors, support regions, fuel types, and others in Climatiq's database
### Estimations[](#estimations)
#### General Emission[](#general-emission)
Calculate the total estimated emissions produced for a particular activity, in kgCO2e, using any emission factor in the Climatiq database.
`Climatiq_Calculate(activityID, region, source, year, unit, amount, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `activityID` | ✓ | Text | An ID describing the activity that to search for. Multiple emission factors can share the same activity\_id, e.g. if they are from a different source or apply to a different region. You can search for `activity_id`s in the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
or via the search formulas. |
| `region` | ✕ | Text | A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor applies. |
| `source` | ✕ | Text | Desired emission factor source. |
| `year` | ✕ | Number | Year in which the activity took place. |
| `unit` | ✓ | Text | Specific unit of the consumed amount, e.g. usd for Money, l for Volume or kg for Weight. See the full list [here](/docs/api-reference/models/parameters)
. |
| `amount` | ✓ | Number | Amount for which the emissions shall be calculated. |
| `showDetails` | ✕ | True/False | Indicates if details on the used emission factor should be shared: Name, source and ID of the used emission factor. |
**Examples** 
#### Air Travel[](#air-travel)
Calculate the total estimated emissions of air travel. The distance between the airports will be calculated using the great circle distance.
`Climatiq_Calculate_Travel_Air(start, end, flightclass, year, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `start` | ✓ | Text | Start location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `end` | ✓ | Text | Destination location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `flightclass` | ✕ | Text | Flight class, can be empty, `average`,`economy`, `business` or `first`. |
| `year` | ✕ | Number | The year in which the travel occurred. |
| `showDetails` | ✕ | True/False | Indicates if these details should also be shared: Distance, direct emissions, indirect emissions & notices. |
**Examples** 
#### Road Travel[](#road-travel)
Calculate the total estimated emissions of road travel. The distance between the locations will be calculated by considering the actual road network where possible.
`Climatiq_Calculate_Travel_Road(start, end, car_type, car_fuel,year, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `start` | ✓ | Text | Start location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `end` | ✓ | Text | Destination location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `car_type` | ✕ | Text | Size of the care. Valid values are `small`, `medium`, `large` and `average`. |
| `car_fuel` | ✕ | Text | Type of fuel used by the car. Valid values are: `petrol`, `diesel`, `hybrid` (cars with a battery that is recharged by the internal combustion engine), `plugin_hybrid` (cars with an internal combustion engine and a battery that can be plugged in), `battery` (for electric vehicles) and `average`. |
| `year` | ✕ | Number | The year in which the travel occurred. |
| `showDetails` | ✕ | True/False | Indicates if these details should also be shared: Distance, direct emissions, indirect emissions & notices. |
**Examples** 
#### Rail Travel[](#rail-travel)
Calculate the total estimated emissions of rail travel. The distance between the locations will be calculated by considering the actual rail network where possible. Otherwise the road distance will be used.
`Climatiq_Calculate_Travel_Rail(start, end, year, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `start` | ✓ | Text | Start location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `end` | ✓ | Text | Destination location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `year` | ✕ | Number | The year in which the travel occurred. |
| `showDetails` | ✕ | True/False | Indicates if these details should also be shared: Distance, direct emissions, indirect emissions & notices. |
**Examples** 
#### Travel based on Spend[](#travel-based-on-spend)
Calculate travel emissions based on spend-based data in any currency by using EXIOBASE emission factors. This calculation automatically takes inflation into account, if the year you spent the money was different than the year of the emission factor.
`Climatiq_Calculate_Travel_Spend(spend_type, currency, amount, location, year, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `spend_type` | ✓ | Text | The type of travel associated with the expenditure. Valid values are: `air`, `road`, `rail`, `sea`, and `hotel`. |
| `currency` | ✓ | Text | The currency in which the money unit is expressed. |
| `amount` | ✓ | Number | The amount of money spent. |
| `location` | ✓ | Text | The location where money was spent, can be any type of free text. |
| `year` | ✕ | Number | The year in which expenditures occurred. |
| `showDetails` | ✕ | True/False | Indicates if these details should also be shared: Distance, used emission factor name, source, region and notices. |
**Examples** 
#### Freight Shipping[](#freight-shipping)
Calculate the total estimated emissions of freight shipping. The distance between the locations will be calculated by considering the actual transport network where possible. By calling our API directly, it's also possible to specify the individual shipment legs as well as the mode of transport used.
`Climatiq_Calculate_IntermodalFreightTransport(start, end, mode, weight, weightUnit, direct, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `start` | ✓ | Text | Start location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `end` | ✓ | Text | Destination location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `mode` | ✓ | Text | Main mode of transport. Valid values are: `air`, `road`, `rail` and `sea` |
| `weight` | ✓ | Number | Weight of the transported goods |
| `weightUnit` | ✓ | Text | Unit of the weight. Valid values are: `g`, `kg`, `t` (metric ton), `lb`, `ton` (US short ton). |
| `direct` | ✓ | True/False | Indicates if in case of sea, air or rail freight the road pre- and post-leg should NOT be added. |
| `showDetails` | ✕ | True/False | Indicates if there details should also be shared: Distance & route. |
**Examples** 
#### Procurement Emissions by Industry Classification Code[](#procurement-emissions-by-industry-classification-code)
Estimate the emissions for a purchase using an industry classification code to identify the type of purchased goods or service. This calculation accounts for tax, trade and transport margins using per-sector and per-country margins from EXIOBASE, if no user-supplied margins are provided. It also corrects for currency exchange rates and inflation adjustments, using rates from the UN Treasury, supplemented with per-industry inflation numbers from Eurostat. You can find details on the methodology [here](/docs/guides/understanding/procurement-spend-based-calculations)
.
`Climatiq_Calculate_Procurement_ByClassification(scheme, code, region, year, currency, amount, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `scheme` | ✓ | Text | The classification scheme used. Valid values are: `mcc`, `unspsc`, `isic4` and `nace2` |
| `code` | ✓ | Text | Specific code of the classification. Please be aware that UNSPSC is only available up to a family level, i.e. the last four digits should be 0. |
| `region` | ✓ | Text | The country in which the goods have been purchased, i.e. ideally the supplier country. Must be a 2-digit country code from [ISO-3166-1 (opens in a new tab)](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
. |
| `year` | ✓ | Number | Year of purchase |
| `currency` | ✓ | Text | Currency of spend, see all available currencies [here](/docs/guides/understanding/currency-support#supported-currencies)
. |
| `amount` | ✓ | Text | Spend amount |
| `showDetails` | ✕ | True/False | Indicates if these details about the calculation methodology should also be shared: Emission factor name, the applied margins for tax, trade, transport and inflation. |
**Examples** 
#### Procurement Emissions by Activity ID[](#procurement-emissions-by-activity-id)
Estimate the emissions for a purchase using an activity ID to identify the type of purchased goods or service. This calculation accounts for tax, trade and transport margins using per-sector and per-country margins from EXIOBASE, if no user-supplied margins are provided. It also corrects for currency exchange rates and inflation adjustments, using rates from the UN Treasury, supplemented with per-industry inflation numbers from Eurostat. You can find details on the methodology [here](/docs/guides/understanding/procurement-spend-based-calculations)
.
`Climatiq_Calculate_Procurement_ByActivityID(activity_id, region, year, currency, amount, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `activityID` | ✓ | Text | An ID describing the activity that to search for. Multiple emission factors can share the same activity\_id, e.g. if they are from a different source or apply to a different region. You can search for `activity_id`s in the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
or via the search formulas. |
| `region` | ✓ | Text | The country in which the goods have been purchased, i.e. ideally the supplier country. Must be a 2-digit country code from [ISO-3166-1 (opens in a new tab)](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
. |
| `year` | ✓ | Number | Year of purchase |
| `currency` | ✓ | Text | Currency of spend, see all available currencies [here](/docs/guides/understanding/currency-support#supported-currencies)
. |
| `amount` | ✓ | Text | Spend amount |
| `showDetails` | ✕ | True/False | Indicates if these details about the calculation methodology should also be shared: Emission factor name, the applied margins for tax, trade, transport and inflation. |
**Examples** 
#### Fuel[](#fuel)
Estimate the emissions of fuel combustion. The calculation also provides details on the associated scope 3, i.e. the well-to-tank emissions. More options are available by directly calling our API.
`Climatiq_Calculate_Fuel(fuel_type, amount, amount_unit, region, year, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `fuel_type` | ✓ | Text | Type of fuel burned, e.g. biodiesel, cng, fuel\_gas, etc. You can make use of our search formula to get a list of available fuel types. |
| `amount` | ✓ | Number | Amount of fuel burned. |
| `amount_unit` | ✓ | Text | Unit of provided amount |
| `region` | ✕ | Text | The country in which the fuel has been purchased. Must be the 2-digit UN code. |
| `year` | ✕ | Number | Year of the fuel consumption |
| `showDetails` | ✕ | True/False | Indicates if these details about the calculation methodology should also be shared: Overall co2e, combustion emissions, wtt emissions and notices. |
**Examples** 
#### Electricity[](#electricity)
Estimate the emissions of electricity usage. If desired, the formula also provides details on the associated scope 3, i.e. the well-to-tank, transmission and distribution losses and their well-to-tank emissions. More options are available by directly calling the API - refer to the documentation for details.
`Climatiq_Calculate_Electricity(amount, region, year, connectionType, calculationType, supplier, energy_source, recs, includeScope3, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `amount` | ✓ | Number | Amount of electricity consumed in kWh. |
| `region` | ✕ | Text | The country or region in which the electricity has been consumed. Must be the 2-digit UN code. |
| `year` | ✕ | Text | Year of the electricity consumption |
| `connectionType` | ✕ | Text | Either the electricity was delivered via the "grid" or via a `direct` line. Default is `grid`. |
| `calculationType` | ✕ | Text | Indicates whether the `location-based` or `market-based` value should be returned, default is `location-based`. |
| `supplier` | ✕ | Text | Available where the region is GB or a US state, a supplier ID can be provided to use market factors for that supplier. Use the respective search formula to find available suppliers. |
| `energy_source` | ✕ | Text | The source that electricity is generated from. Valid values are `renewable` or specific fuel types such as `natural_gas`, `coal`, `biomass` and `nuclear`. |
| `recs` | ✕ | Number | Quantity of RECs (Renewable Energy Certificates) to apply for market-based emission calculations. |
| `includeScope3` | ✕ | True/False | Indicates if the scope 3 emissions should be considered in the calculation, default is false. |
| `showDetails` | ✕ | True/False | Indicates if details should also be shared: Overall co2e, combustion emissions, wtt emissions and notices. |
**Examples** 
#### Cloud Computing - Virtual Machines[](#cloud-computing---virtual-machines)
Estimate the emissions for using virtual machines provided by the common cloud providers (AWS, GCP and Azure), including both the embodied emissions (meaning the emissions related to the manufacturing and disposal of the physical components, expressed per CPU hour over the expected lifetime of the hardware) and the electricity usage of the different components. More options are available by directly calling our API.
`Climatiq_Calculate_CloudVMs(vm_type, region, provider, duration, duration_unit, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `vm_type` | ✓ | Text | The specific virtual machine instance type you are using. |
| `region` | ✓ | Text | The region that is relevant for the calculation, as specified by the cloud provider. |
| `provider` | ✓ | Text | The provider used, valid values are: `aws`, `azure` and `gcp`. |
| `duration` | ✓ | Number | How long the machine is running for. |
| `duration_unit` | ✓ | Text | The unit the duration value is in. Valid values are `ms`, `s`, `m`, `h`, `day`, `year`. |
| `showDetails` | ✕ | True/False | Indicates if details about the calculation methodology should also be shared: Overall emissions, the memory usage energy emissions, the cpu usage energy emissions and the embodied emissions. |
**Examples** 
#### CBAM[](#cbam)
Calculate total estimated emissions produced for a particular Combined Nomenclature (CN) code, for use with CBAM reporting.
`Climatiq_Calculate_CBAM(cn_code, production_region, weight, weight_unit, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `cn_code` | ✓ | Text | The combined nomenclature code for the imported goods. |
| `production_region` | ✓ | Text | The region the goods were produced in. If you specify "ROW" then this will return the EU default factors |
| `weight` | ✓ | Number | The weight of the imported goods in the defined unit. |
| `weight_unit` | ✓ | Text | Unit of the weight. Valid values are: `g`, `kg`, `t` (metric ton), `lb`, `ton` (US short ton). |
| `showDetails` | ✕ | True/False | Indicates if details should also be shared (overall co2e, estimated costs, the emission factor name, direct emissions, indirect emissions and notices). |
**Examples** 
### Autopilot[](#autopilot)
Autopilot is an AI-powered calculation endpoint designed to automate spend- and activity-based emission estimates. It uses a proprietary natural language processing (NLP) model paired with Climatiq’s scientific expertise to streamline complex emission calculations, making carbon insights accessible to non-experts.
Autopilot significantly reduces the time and manual effort spent identifying the appropriate emission factors and mapping activity data. Capable of ingesting any taxonomy and unstructured data, this feature matches raw text content to the correct emission factors and delivers accurate and compliant emission estimates.
Leveraging a built-in expert review mechanism and machine learning, Autopilot's matching algorithm consistently refines its precision. This is achieved through active feedback and continuous improvement of the underlying NLP model.
#### General Estimation[](#general-estimation)
Calculate total estimated emissions produced for a particular activity, in kgCO2e, using free-text input. The best matching emission factor will automatically be selected and used for the calculation.
`Climatiq_Autopilot(text, domain, unit, amount, year, region, region_fallback, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `text` | ✓ | Text | The free-form input text, such as an activity name, service or material name. |
| `domain` | ✓ | Text | Defines the scope of emission factors to be searched, see available domains [here](/docs/api-reference/autopilot#domains)
. |
| `unit` | ✓ | Text | Specific unit of the consumed amount, e.g. usd for Money, l for Volume or kg for Weight. See the full list [here](/docs/api-reference/autopilot#request)
. |
| `amount` | ✓ | Number | Amount for which the emissions shall be calculated. |
| `year` | ✕ | Number | Year in which the activity took place. |
| `region` | ✕ | Text | A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor should apply. |
| `region_fallback` | ✕ | True/False | Indicates if Autopilot should search in other regions, if no factor can be found for the given region. |
| `showDetails` | ✕ | True/False | Indicates if details on the used emission factor should be shared: Name, source and ID. |
**Examples** 
#### Suggest[](#suggest)
Receive a number of suggested Emission Factors for a particular input query. You can adjust the number of suggestions to return. Suggestions are ordered by the most likely match first. For each result, a suggestion ID is returned, which you can apply via the `Autopilot_EstimateSuggest` formula to calculate the respective emissions.
`Climatiq_Autopilot_Suggest(results, text, domain, unit_type, source, year, region, region_fallback, excludeEcoinvent, flatten, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `results` | ✓ | Number | The maximum number of suggestions to receive. Autopilot will return as many suitable suggestions as it can find, up to the max number requested, or at most 20 suggestions. |
| `text` | ✓ | Text | The free-form input text, such as an activity name, service or material name. |
| `domain` | ✓ | Text | Defines the scope of emission factors to be searched, see available domains [here](/docs/api-reference/autopilot#domains)
. |
| `unit_type` | ✕ | Text | The unit types of the activity, can be Weight, Money, Volume and Number. When searching across multiple types, split them with a comma, e.g. "Money,Volume" |
| `source` | ✕ | Text | The source(s) in which should be searched in. If you search in multiple sources, split them with a comma, e.g. "BEIS,EPA,Ecoinvent" |
| `year` | ✕ | Number | Year in which the activity took place. |
| `region` | ✕ | Text | A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor should apply. |
| `region_fallback` | ✕ | True/False | Indicates if Autopilot should search in other regions, if no factor can be found for the given region. |
| `excludeEcoinvent` | ✕ | True/False | Indicates if Ecoinvent emission factors should be disregarded during the Matching |
| `flatten` | ✕ | True/False | Indicates if the calculation details of the matches should also be shared, i.e. estimated emissions and the details of the used emission factor (name, source, Climatiq UUID) |
| `showDetails` | ✕ | True/False | Indicates if details on the used emission factor should be shared: Name, source and ID. |
**Example - Flattened** 
**Example - Not Flattened** 
#### Estimate Suggest[](#estimate-suggest)
Calculate an emission estimation for an emission factor match. To calculate an emission estimation you will need to first find an emission factor using the Suggest endpoint. When you have selected an emission factor, you can request for a calculation using the suggestion ID.
`Climatiq_Autopilot_EstimateSuggest(suggestID, unit, amount, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `suggestID` | ✓ | Text | An ID generated via the Suggest function. |
| `unit` | ✓ | Text | Specific unit of the consumed amount, e.g. usd for Money, l for Volume or kg for Weight. See the full list [here](/docs/api-reference/autopilot#request)
. |
| `amount` | ✓ | Number | Amount for which the emissions shall be calculated. |
| `showDetails` | ✕ | True/False | Indicates if details on the used emission factor should be shared: Name, source and ID. |
**Example - Flattened** 
### Search
#### Search Emission Factors[](#search-emission-factors)
Search the emission factor database of Climatiq. Please be aware that this might only return a subset of results (depending on the number of results specified). The search works in the same way as ou[Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
\- The formula returns a table of results, so make sure the surrounding cells are empty when using this formula. Depending on whether an existing Climatiq subscription to use the raw emission factors is in place, these will also be returned as part of the response. If you want to gain access to the raw emission factors, please [reach out to our team (opens in a new tab)](https://www.climatiq.io/contact-us)
.
`Climatiq_Search_EmissionFactors(query, numberOfResults, sector, category, source, region, unit_type, lca_stage)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `query` | ✕ | Text | A free-text query that will match ids, names, descriptions, etc. of emission factors. This uses fuzzy matching, so your query does not need to be precise. |
| `numberOfResults` | ✕ | Number | The number of results to be shared. The maximum value is 500. |
| `sector` | ✕ | Text | Filters by emission factor sector. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `category` | ✕ | Text | Filters by emission factor category. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `source` | ✕ | Text | Filters by emission factor source. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `region` | ✕ | Text | Filters by emission factor region. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `year` | ✕ | Number | Filters by applicable year. |
| `unit_type` | ✕ | Text | Filters by emission factor unit type, e.g. Money or Volume. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `lca_stage` | ✕ | Text | Filters by Life Cycle Assessment stage, e.g. well-to-tank. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
**Examples** 
#### Available Regions[](#available-regions)
Find available regions for a specific query. At least one of the parameters needs to be set.
`Climatiq_Search_Regions(query, sector, category, source)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `query` | ✕ | Text | A free-text query that will match ids, names, descriptions, etc. of emission factors. This uses fuzzy matching, so your query does not need to be precise. |
| `sector` | ✕ | Text | Filters by emission factor sector. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `category` | ✕ | Text | Filters by emission factor category. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `source` | ✕ | Text | Filters by emission factor source. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
**Examples** 
#### Available Electricity Suppliers[](#available-electricity-suppliers)
Find available electricity suppliers for a specific region to be used for the electricity emission estimation. Currently only available for GB and US regions.
`Climatiq_Search_AvailableElectricitySuppliers(region)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `region` | ✕ | Text | Filters by emission factor region. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
**Examples** 
#### Available Fuel Types[](#available-fuel-types)
Pulls a list of fuel types available to be used in the fuel emissions formula for a specific unit type.
`Climatiq_Search_AvailableFuelTypes(unit_type)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `unit_type` | ✕ | Text | Filters by emission factor unit type, e.g. Money or Volume. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
**Examples** 
[Microsoft Excel Add-In](/docs/guides/tutorials/excel-addin "Microsoft Excel Add-In")
[Autopilot Integration Guide](/docs/guides/tutorials/autopilot-integration "Autopilot Integration Guide")
---
# Energy v1 - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Energy
Energy v1 ADD-ONADD-ON
======================
To see the changes since the preview versions, see our [changelog](/docs/changelogs/api-release/energy-v1)
The energy endpoints automatically calculates the greenhouse gas emissions associated with the consumed energy based on relevant emission factors. These factors are determined based on the specific type of energy and the region where it is consumed, ensuring accurate carbon footprint calculations for your organization.
This feature can be used to help businesses estimate and report their scope 1, 2 and associated scope 3 emissions under the GHG Protocol. It also meets the requirements of the SBTi and covers market-based and location-based approaches for electricity use. The Energy Endpoint has passed a validation audit confirming compliance with the requirements of ISO 14067 and GHG Protocol - Product Life Cycle Accounting & Reporting Standard. Please see the Climatiq [Trust page (opens in a new tab)](https://trust.climatiq.io/)
for the document of conformity.
For extra information about our methodology for GHG Protocol scopes 2 and 3.3 calculation, please view the [scope 2](/docs/guides/understanding/selecting-electricity-efs)
and [scope 3.3 FERA guides](/docs/guides/understanding/selecting-electricity-efs-scope-3)
.
Electricity use[](#electricity-use)
------------------------------------
POST Calculate the estimated greenhouse gas emissions for electricity use, including both grid electricity and direct-line electricity. This endpoint allows you to obtain accurate carbon footprint calculations for your organization's purchased electricity.
**IEA data**
By default the Electricity calculator uses publicly published emission factors from various official sources covering 63 countries. For greater coverage and consistency you also have the option to purchase a premium license to emission factors from the International Energy Agency (IEA) increasing coverage to 149 countries. [Contact us (opens in a new tab)](https://www.climatiq.io/contact-us)
https://api.climatiq.io/energy/v1/electricity
### Request[](#request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* regionrequired string
The region or country where the electricity was consumed, usually a country but could be US / Australian / Canadian state / province or US eGrid. A US zip code can be provided in the format `US-XXXXX` or a UN/LOCODE in the format `XX-YYY`. See also [choosing a region below](/docs/api-reference/energy#choosing-a-region)
.
* yearinteger
Default value: Latest year available
The year for which the greenhouse gas emissions are being calculated.
Default Value
Latest year available
* amount[Energy](/docs/api-reference/models/parameters#energy)
object
Default value: Sum of the components
The total electricity used.
Default Value
Sum of the components
* recs[Energy](/docs/api-reference/models/parameters#energy)
object
Quantity of RECs (Renewable Energy Certificates) to apply.
* source\_setstring
Default value: `"iea"` if the API key used has access to the premium IEA dataset, otherwise `"core"`
Specifies which set of emission factors the caller would like to use. Valid values are `core` or `iea`
Default Value
`"iea"` if the API key used has access to the premium IEA dataset, otherwise `"core"`
* componentsarray of Component objects
An array containing the different components of the electricity consumption and their associated details.
➕ Show child attributes
An implied residual component will be added to make up any difference between the total `amount` of energy in the request and the sum of the `amount` of energy in each component.
curl --request POST \ --url https://api.climatiq.io/energy/v1/electricity \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "year": 2023, "region": "GB", "source_set": "core", "amount": { "energy": 5000, "energy_unit": "kWh" }, "recs": { "energy": 1000, "energy_unit": "kWh" }, "components": [ { "amount": { "energy": 1000, "energy_unit": "kWh" }, "connection_type": "grid", "supplier": "british_gas" }, { "amount": { "energy": 1000, "energy_unit": "kWh" }, "connection_type": "direct", "loss_factor": 0.05, "energy_source": "natural_gas" }, { "amount": { "energy": 1000, "energy_unit": "kWh" }, "connection_type": "direct", "energy_source": "renewable" } ]}'
### Response[](#response)
The response includes estimates for the greenhouse gas emissions associated with electricity use.
Response parameters
* location[Energy reporting quad](/docs/api-reference/energy#energy-reporting-quad)
The estimates for greenhouse gas emissions based on the location of consumption.
* market[Energy reporting quad](/docs/api-reference/energy#energy-reporting-quad)
The estimates for greenhouse gas emissions based on market method (purchases).
* noticesarray of [Notices](/docs/api-reference/energy#notice)
Any notices about deficiencies or peculiarities of the calculation.
{ "location": { "consumption": { "co2e": 1007, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 999.4, "ch4": 0.1169, "n2o": 0.01451 } }, "well_to_tank": { "co2e": 200.9, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "transmission_and_distribution": { "co2e": 74.07, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid: T&D losses", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 73.45, "ch4": 0.00941, "n2o": 0.001232 } }, "well_to_tank_of_transmission_and_distribution": { "co2e": 15.24, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid: T&D losses", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } } }, "market": { "consumption": { "co2e": 889.6, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar4_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid - residual mix", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid - supplier British Gas", "source": "Electricity Info", "source_dataset": "Fuel Mix of UK Domestic Electricity Suppliers", "year": "2022", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 888.9, "ch4": null, "n2o": null } }, "well_to_tank": { "co2e": 148.9, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_mixed_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid - residual mix", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid - supplier British Gas", "source": "Electricity Info", "source_dataset": "Fuel Mix of UK Domestic Electricity Suppliers", "year": "2022", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "transmission_and_distribution": { "co2e": 74.07, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid: T&D losses", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 73.45, "ch4": 0.00941, "n2o": 0.001232 } }, "well_to_tank_of_transmission_and_distribution": { "co2e": 15.24, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Electricity supplied from grid", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid: T&D losses", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } } }, "notices": [ { "severity": "info", "code": "recs_subtracted_market_generation", "message": "Market generation components were subtracted for RECs" }, { "severity": "warning", "code": "global_default_wtt_used", "message": "Applying global default well to tank percentage due to absence of an applicable emissions factor. For more accurate market well to tank emissions, explicitly provide a fuel mix." } ]}
### Choosing a region[](#choosing-a-region)
Regions are currently only available where grid emission data is available. We plan to expand this coverage over time. In countries where we have coverage, you can use a [country-level region code](/docs/api-reference/regions#country-level-region-code)
to specify the country, or an [extended region code](/docs/api-reference/regions#extended-region-code)
to specify a subdivision, or a location within that subdivision. In the US the preferred method is to use a zip code in the format `US-XXXXX` in order to most accurately choose both eGrid and state-based factors.
The suggested way to find available regions is to make a request without setting a `region` and see which ones are indicated as being available in the error response.
#### Request[](#request-1)
curl --request POST \ --url https://api.climatiq.io/energy/v1/electricity \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "region": "", "source_set": "core"}'
#### Response[](#response-1)
{ "error": "bad_request", "error_code": "no_location_found", "message": "The supplied region is not supported", "valid_values": { "region": [ "AE", "AR", "AT", "AU", "AU-ACT", "AU-NSW", "AU-NT", "AU-QLD", "AU-SA", "AU-TAS", "AU-VIC", "AU-WA", "BA", "BD", "BE", "BG", "BR", "CA", "CA-AB", "CA-BC", "CA-MB", "CA-NB", "CA-NL", "CA-NS", "CA-NT", "CA-NU", "CA-ON", "CA-QC", "CA-SK", "CA-YT", "CH", "CN", "CO", "CY", "CZ", "DE", "DK", "EE", "ES", "EU", "FI", "FR", "GB", "GR", "HR", "HU", "ID", "IE", "IN", "IS", "IT", "JP", "KR", "LT", "LU", "LV", "ME", "MT", "MX", "NG", "NL", "NO", "NP", "NZ", "PH", "PK", "PL", "PT", "RO", "RS", "RU", "SA", "SE", "SI", "SK", "TH", "TR", "US", "US-AK", "US-AKGD", "US-AKMS", "US-AL", "US-AR", "US-AZ", "US-AZNM", "US-CA", "US-CAMX", "US-CO", "US-CT", "US-DC", "US-DE", "US-ERCT", "US-FL", "US-FRCC", "US-GA", "US-HI", "US-HIMS", "US-HIOA", "US-IA", "US-ID", "US-IL", "US-IN", "US-KS", "US-KY", "US-LA", "US-MA", "US-MD", "US-ME", "US-MI", "US-MN", "US-MO", "US-MROE", "US-MROW", "US-MS", "US-MT", "US-NC", "US-ND", "US-NE", "US-NEWE", "US-NH", "US-NJ", "US-NM", "US-NV", "US-NWPP", "US-NY", "US-NYCW", "US-NYLI", "US-NYUP", "US-OH", "US-OK", "US-OR", "US-PA", "US-PR", "US-PRMS", "US-RFCE", "US-RFCM", "US-RFCW", "US-RI", "US-RMPA", "US-SC", "US-SD", "US-SPNO", "US-SPSO", "US-SRMV", "US-SRMW", "US-SRSO", "US-SRTV", "US-SRVC", "US-TN", "US-TX", "US-UT", "US-VA", "US-VT", "US-WA", "US-WI", "US-WV", "US-WY", "VN", "ZA" ] }}
### Choosing a supplier[](#choosing-a-supplier)
Suppliers are currently only available in US states and in the United Kingdom. The suggested way to find available `suppliers`'s is to make a request without setting a `supplier` (but setting `amount` and `region`) and see which `supplier`s are indicated as being available in the error response.
#### Request[](#request-2)
curl --request POST \ --url https://api.climatiq.io/energy/v1/electricity \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "region": "US-CA", "components": [ { "amount": { "energy": 0, "energy_unit": "kWh" }, "supplier": "" } ]}'
#### Response[](#response-2)
The available suppliers will depend on the region.
{ "error": "bad_request", "error_code": "invalid_input", "message": "No emission factors exist with the given supplier `` in the specified region. This error will contain the valid suppliers in the requested region.", "valid_values": { "supplier": [ "algonquin_power_and_utilities_corp_liberty_utilities", "edison_international_southern_california_edison", "pgande_corporation_pacific_gas_and_electric_company", "puget_sound_energy" ] }}
### Batch Electricity Use[](#batch-electricity-use)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/energy/v1/electricity/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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
Heat and Steam use[](#heat-and-steam-use)
------------------------------------------
POST Calculate the estimated greenhouse gas emissions for heat and steam use. This endpoint allows you to obtain accurate carbon footprint calculations for your organization's purchased heat and steam.
https://api.climatiq.io/energy/v1/heat
### Request[](#request-3)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* regionrequired string
The country where the heat and steam was consumed.
* componentsrequired array of Component objects
An array containing the different components of the heat and steam consumption and their associated details.
Each component within the `components` array corresponds to a purchase of heat and steam under some contract, it should include the following parameters: (outside of DE / GB / US, either the `energy_source` or the `co2e_kg_per_kwh` must be provided)
✖ Hide child attributes
* * *
components\[x\].amountrequired [Energy](/docs/api-reference/models/parameters#energy)
object
The total heat and steam purchased
* * *
components\[x\].co2e\_kg\_per\_kwhfloat
Contract emission factor for the component in kg per kWh
* * *
components\[x\].energy\_sourcestring
The source that the heat is generated from. Valid values are `renewable` or specific fuel types such as `natural_gas`, `coal`, `biomass`
* * *
components\[x\].loss\_factorfloat or string
Default value: `medium`
The distribution loss factor for this component. Can either be a number or one of the strings `"low"`, `"medium"` or `"high"`
Default Value
`medium`
* yearinteger
Default value: Latest year available
The year for which the greenhouse gas emissions are being calculated.
Default Value
Latest year available
curl --request POST \ --url https://api.climatiq.io/energy/v1/heat \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "year": 2021, "region": "DE", "components": [ { "amount": { "energy": 1000, "energy_unit": "kWh" }, "loss_factor": 0.06 }, { "amount": { "energy": 1000, "energy_unit": "kWh" }, "loss_factor": 0.1, "energy_source": "natural_gas" }, { "amount": { "energy": 1000, "energy_unit": "kWh" }, "energy_source": "renewable" } ]}'
### Response[](#response-3)
The response includes estimates for the greenhouse gas emissions associated with heat and steam use.
Response parameters
* estimates[Energy reporting quad](/docs/api-reference/energy#energy-reporting-quad)
The estimates for greenhouse gas emissions.
* noticesarray of [Notices](/docs/api-reference/energy#notice)
Any notices about deficiencies or peculiarities of the calculation.
{ "estimates": { "consumption": { "co2e": 479.9, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "District heating", "source": "UBA", "source_dataset": "Emissionsbilanz erneuerbarer Energietraeger", "year": "2021", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2021", "year": "2021", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 475.9, "ch4": 0.08444, "n2o": 0.00541 } }, "well_to_tank": { "co2e": 78.89, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar4_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "District heating", "source": "UBA", "source_dataset": "Emissionsbilanz erneuerbarer Energietraeger", "year": "2021", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2021", "year": "2021", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "transmission_and_distribution": { "co2e": 41.37, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar6_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "District heating", "source": "UBA", "source_dataset": "Emissionsbilanz erneuerbarer Energietraeger", "year": "2021", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2021", "year": "2021", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": 41.09, "ch4": 0.005978, "n2o": 0.0003647 } }, "well_to_tank_of_transmission_and_distribution": { "co2e": 6.861, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar4_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "District heating", "source": "UBA", "source_dataset": "Emissionsbilanz erneuerbarer Energietraeger", "year": "2021", "region": "DE", "region_name": "Germany" }, { "data_category": "emission_factor", "name": "Natural gas - 100% mineral blend (net CV)", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2021", "year": "2021", "region": "GB", "region_name": "United Kingdom" }, { "data_category": "emission_factor", "name": "Renewables", "source": "Climatiq", "source_dataset": "Climatiq", "year": "2022", "region": "GLOBAL", "region_name": "Global" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } } }}
### Batch Heat and Steam Use[](#batch-heat-and-steam-use)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/energy/v1/heat/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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
Fuel Use[](#fuel-use)
----------------------
POST Calculate the estimated greenhouse gas emissions for fuel combustion.
https://api.climatiq.io/energy/v1/fuel
### Request[](#request-4)
The request to the fuel combustion endpoint accepts the following parameters included in the request body. Except for `fuel_type` and `amount`, which must match exactly, any parameters that cannot be matched to an emission factor will be _ignored_, e.g. this means that the emission factors might be for a different region than you selected. In the event of a mismatch, a notice will be included in the response.
Request parametersShould be sent as a JSON object in the body
* fuel\_typerequired string
The type of fuel burned. See [choosing a `fuel_type`](/docs/api-reference/energy#choosing-a-fuel_type)
for how to choose this.
* amountrequired [Energy](/docs/api-reference/models/parameters#energy)
/[Volume](/docs/api-reference/models/parameters#volume)
/[Weight](/docs/api-reference/models/parameters#weight)
object
The amount of fuel burned.
* regionstring
The region or country where the fuel was burned.
* yearinteger
Default value: Latest year available
The year in which the fuel was burned.
Default Value
Latest year available
curl --request POST \ --url https://api.climatiq.io/energy/v1/fuel \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "fuel_type": "biodiesel_bio_100", "amount": { "volume": 5000, "volume_unit": "l" }, "region": "GB", "year": 2023}'
### Response[](#response-4)
The response includes estimates for the greenhouse gas emissions associated with fuel combustion.
Response parameters
* combustion[Energy estimate](/docs/api-reference/energy#energy-estimate)
Estimate of emissions from fuel combustion
* well\_to\_tank[Energy estimate](/docs/api-reference/energy#energy-estimate)
Estimate of upstream emissions. (This could be empty in cases where we can't estimate the WTT but can estimate the combustion, a notice will be included in this case)
* noticesarray of [Notices](/docs/api-reference/energy#notice)
Any notices about deficiencies or peculiarities of the calculation.
{ "combustion": { "co2e": 837.6, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Off road biodiesel", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" } ], "co2_biogenic": 11950, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "well_to_tank": { "co2e": 2238, "co2e_unit": "kg", "co2e_calculation_method": "ipcc_ar5_gwp100", "source_trail": [ { "data_category": "emission_factor", "name": "Off road biodiesel", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023", "region": "GB", "region_name": "United Kingdom" } ], "co2_biogenic": null, "constituent_gases": { "co2": null, "ch4": null, "n2o": null } }, "notices": []}
### Choosing a `fuel_type`[](#choosing-a-fuel_type)
The suggested way to find the available `fuel_types` is to make a request without setting the `fuel_type` (but setting `amount` and `region`) and see which `fuel_type`s are indicated as being available in the error response. `region` can also be omitted to see all `fuel_type`s available globally.
#### Request[](#request-5)
curl --request POST \ --url https://api.climatiq.io/energy/v1/fuel \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "amount": { "weight": 0, "weight_unit": "g" }, "region": "US"}'
#### Response[](#response-5)
The available `fuel_type`s will depend on the unit and region.
{ "error": "bad_request", "error_code": "invalid_input", "message": "No emission factors exist with the given fuel type. This error will contain the valid fuel types for the provided unit type and for this region.", "valid_values": { "fuel_type": [ "agricultural_byproducts_bio_100", "coal_and_coke_mixed", "coal_anthracite", "coal_bituminous", "coal_coke", "coal_lignite", "coal_sub_bituminous", "peat_bio_100", "petroleum_coke", "plastics", "solid_byproducts", "tires", "waste_solid_municipal", "wood_and_wood_residuals_bio_100" ] }}
### Batch Fuel Use[](#batch-fuel-use)
POST For bulk data-processing, this endpoint has a [batch endpoint variant](/docs/api-reference/batch-endpoints)
allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/energy/v1/fuel/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](/docs/api-reference/batch-endpoints)
for more information about how batch endpoints work and how to handle errors.
Response models[](#response-models)
------------------------------------
Response formats shared between the above endpoints.
### Energy reporting quad[](#energy-reporting-quad)
For electricity (market and location) and heat and steam, the API reports 4 estimates, one for scope 2 (consumption) emissions and each of the 3 scope 3.3 (FERA) emissions estimates:
| Attribute | Type | Description |
| --- | --- | --- |
| **consumption** | _[Energy estimate](/docs/api-reference/energy#energy-estimate)
_ | Estimates of the greenhouse gas emissions that result from generating the consumed energy. |
| **transmission\_and\_distribution** | _[Energy estimate](/docs/api-reference/energy#energy-estimate)
_ | Estimates of the greenhouse gas emissions that result from generating the energy which is subsequently lost during the processes of transmission and distribution. |
| **well\_to\_tank** | _[Energy estimate](/docs/api-reference/energy#energy-estimate)
_ | Estimates of the greenhouse gas emissions that result from obtaining the fuel used for generating the consumed energy. |
| **well\_to\_tank\_of\_transmission\_and\_distribution** | _[Energy estimate](/docs/api-reference/energy#energy-estimate)
_ | Estimates of the greenhouse gas emissions that result from obtaining the fuel used for generating the energy which is subsequently lost during the processes of transmission and distribution. |
### Energy estimate[](#energy-estimate)
Response parameters
* co2efloat
The total greenhouse gas emissions associated with the consumed energy, expressed in kilograms (kg).
* co2e\_unitstring
The unit in which the CO2e field is expressed. The value of this is always `kg`
* co2e\_calculation\_methodstring
Which calculation methodology that was used for the calculation. The value of this is either `"ipcc_ar4_gwp100"`, `"ipcc_ar5_gwp100"`, `"ipcc_ar6_gwp100"` or `"ipcc_mixed_gwp100"`. [Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation)
* source\_trailarray of [Source Data Points](/docs/api-reference/source-trail#source-data-point)
An array of data points that help explain and provide trust in the calculation. Click to view more details about [Source Trail](/docs/api-reference/source-trail)
.
* co2\_biogenicfloat or null
The biogenic CO2 emissions associated with the consumed energy, expressed in kilograms (kg). This is not included in the `co2e` total.
* constituent\_gases[Energy constituent gases](/docs/api-reference/energy#constituent-gases)
or null
Breakdown of the main 3 greenhouse gases which constitute the co2e estimate, they may not sum to the whole co2e value in the case of other, non-itemized gases. A `null` means the emission factor used only provided co2e without a constituent gase breakdown.
**Absence of Estimation model**
Our older calculation endpoints always return the [`Estimation model`](/docs/api-reference/models/estimation#estimation)
which gives information about the emission factor that was used in the calculation and how it was applied, but we haven't implemented that for our newest features. This is because the complexity of the calculations performed by our new emissions calculators means that we are unable to explain the calculations adequately using the estimation model. Below are the new features which replace the Estimation model and which we are trialing on the Energy feature. If you have some requirements for calculation transparency please [get in contact (opens in a new tab)](https://www.climatiq.io/contact-us)
.
### Constituent Gases[](#constituent-gases)
| Attribute | Type | Description |
| --- | --- | --- |
| **co2** | _number_ | Estimation of kg of CO2 emissions for the activity |
| **ch4** | _number_ | Estimation of kg of CH4 emissions for the activity |
| **n2o** | _number_ | Estimation of kg of N2O emissions for the activity |
### Notice[](#notice)
The `notices` array can contain objects like these:
| Notice attributes | Type | Description |
| --- | --- | --- |
| **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 machine-readable categorization of the notice to allow automatic handling. |
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:
#### For Electricity[](#for-electricity)
| Notice code value | description |
| --- | --- |
| `supplier_mix_used_for_residual` | Unable to find a residual mix factor for the requested region, the supplier mix will be used instead, this will likely result in underestimating this portion of the energy usage. |
| `global_default_wtt_used` | Applying a global default well to tank percentage due to absence of an applicable emissions factor. For more accurate market well to tank emissions, explicitly provide a fuel mix. |
| `ignored_parameter` | A parameter in the request was ignored in favor of some more precise piece of data |
| `recs_subtracted_market_generation` | Market components were subtracted for recs |
| `recs_subtracted_market_transmission_and_distribution` | Market T&D components were subtracted for recs |
#### For Fuel Combustion[](#for-fuel-combustion)
| Notice code value | description |
| --- | --- |
| `no_region_match` | A different region was selected as the requested region was not available for the selected fuel type and unit. |
| `wtt_not_estimated` | Failed to estimate well to tank: a WTT factor wasn't found with the requested fuel type. |
[Autopilot (preview 1)](/docs/api-reference/autopilot/autopilot-v1-preview1 "Autopilot (preview 1)")
[Energy v1 (preview 2)](/docs/api-reference/energy/energy-v1-preview2 "Energy v1 (preview 2)")
---
# Guide to the Microsoft Excel Add-In - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Microsoft Excel Add-In
Guide to the Microsoft Excel Add-In
===================================
**Utilize Climatiq-specific functions in Microsoft Excel to seamlessly convert your business activity data into carbon estimates across various activities, such as travel, energy usage, and fuel consumption.**
Overview[](#overview)
----------------------
Climatiq’s Microsoft Excel Add-In transforms your spreadsheets into a powerful environmental impact assessment tool. No coding is required, allowing you to quickly create proofs of concept and collaborate with your team for feedback before fully integrating Climatiq’s API or developing advanced features. The Add-In lets you visualize results directly in Excel and share detailed emission reports, streamlining approval for sustainability projects with reliable data.
Since this tool provides a simplified version of our API endpoints, we recommend reviewing our documentation or using the guided Postman collection if you are interested in accessing the full capabilities of the API.
**Explore our Demo to get started quickly**
You can easily explore the capabilities of the Add-In be using the demo file we have prepared. It provides different examples on inputs for all available formulas, which you can also immediately try yourself.
[Download the Demo](/docs/guides/integrations/Climatiq_ExcelAdd-In_Demo.xlsx)
Getting Started[](#getting-started)
------------------------------------
Access to Climatiq's API generally requires a commercial subscription. However, for this Add-In, we offer a free starter plan that includes up to 500 emission estimations per month, granting access to all advanced emission calculations, e.g. the emission estimations for travel, freight, energy and the Autopilot. Without this plan or a commercial subscription, functionality will be limited to basic estimations, i.e. [General Estimates](/docs/guides/tutorials/excel-addin#general-emission)
and [General Search](/docs/guides/tutorials/excel-addin#search-emission-factors)
. Upon installing the Add-In via Microsoft AppSource, you will automatically be enrolled in this plan. Alternatively, you can sign up for the starter plan [here (opens in a new tab)](https://www.climatiq.io/excel-integration-access)
. If you anticipate commercial usage or usage beyond the free starter plan limit, please [reach out to our team (opens in a new tab)](https://www.climatiq.io/contact-us)
.
If you prefer a video introduction, here is a 2 minute quickstart guide:
### Installation of the Add-In[](#installation-of-the-add-in)
You can install the Add-In from [Microsoft AppSource (opens in a new tab)](https://appsource.microsoft.com/en-gb/product/office/wa200007333?tab=overview)
. Once installed, it will appear under the "Add-In" menu in the Excel toolbar.
### Setting the API key[](#setting-the-api-key)
Next, you'll need to set an API key for the Add-In to call Climatiq's API. Follow [these steps](/docs/guides/how-tos/getting-api-key)
to obtain your API key. Once you have it, set the key by executing the following function:
The API key will be stored permanently for this specific file and other users using this file will also be able to make use of the functions. This also means that you will have to set the key once for every new Excel file in which you'd want to use this integration. You can always overwrite the stored API key by calling the above mentioned function again.
### Explore the demo[](#explore-the-demo)
You can familiarize yourself with the Add-In be exploring the demo file we have prepared. It provides different examples on inputs for all available formulas. You can download the demo [here](/docs/guides/integrations/Climatiq_ExcelAdd-In_Demo.xlsx)
.
Support and Feedback[](#support-and-feedback)
----------------------------------------------
In case of questions, please reach out to the Climatiq team via the website chat or the [support form (opens in a new tab)](https://www.climatiq.io/support)
. We also appreciate any feedback being shared through these channels.
General Concepts and Notices[](#general-concepts-and-notices)
--------------------------------------------------------------
To get the most out of the Add-In, it's important to familiarize yourself with the following concepts.
### "ShowDetails" Flag[](#showdetails-flag)
For all Estimation and Autopilot functions, you can choose whether to receive additional calculation details or just the estimated CO2e value in the response. Refer to the documentation for each [function](/docs/guides/tutorials/excel-addin#functions)
to see which details are available. The additional details will be stored in the cells following the one containing the function.
### Optional Parameters[](#optional-parameters)
Typically not all parameters are required when using the functions. The documentation indicates which ones are required and which ones are optional. In case no value should be used for the optional parameters, please simply leave them empty, e.g. `Climatiq.Calculate_Travel_Air(start, end, flightclass)` as `Climatiq.Calculate_Travel_Air("BER", "JFK")`. 
### Error Handling[](#error-handling)
In addition to common errors, functions will return specific errors from the Climatiq API if an input is incorrect, or if the provided API key is invalid, or a suitable emission factor cannot be found by the API.
### Populate Header Rows[](#populate-header-rows)
Many of the formulas will retrieve results across multiple cells, especially when the "showDetails" flag is being used. To know which different values are being retrieved and to automatically populate the headers for the result columns, there is a collection of dedicated formulas available for this. For every Calculate and Autopilot formula, you can simply add `_Headers` to the original formula name. Additionally, you can indicate, whether the detail column headers should also be populated. A few examples: `=Climatiq.Autopilot_Headers(TRUE)`, `=Climatiq.Calculate_Travel_Air_Headers()` and `=Climatiq.Calculate_IntermodalFreightTransport_Headers(TRUE)`
### API Consumption and Recalculation of Results[](#api-consumption-and-recalculation-of-results)
By default, Excel will re-calculate the results for functions everytime an input changes or the file is reloaded. Every re-calculation will also count as a call to the Climatiq API. To avoid overconsumption of your subscribed API calls, it is recommended to copy-paste the values of the calculations into the cells as soon as the calculations are complete. To do this, you should select the cells with the calculation results, copy them and paste them back into these cells via Edit > Paste Special > Values only. You can disable the automatic recalculations under the settings for "Calculation options" in the "Formula" ribbon.
### Documentation within the Add-In[](#documentation-within-the-add-in)
To see an overview of the available functions in a sidebar within Excel, simply open the documentation by clicking the Climatiq icon in the main menu bar.
### Access to all functionalities[](#access-to-all-functionalities)
By default, when signing up for the Climatiq API, the initial access only covers the usage of the general estimation and search capabilities. For any advanced calculations, e.g. emission estimations for air travel, additional access needs to be granted for your API key. Otherwise the following error will be shown when trying to make use of an advanced features, that has not yet been enabled for your account:
`Your authentication is valid, but you do not have access to this feature.`
To enable these advanced features, you can sign up to a free starter plan, which covers up to 500 emission estimations monthly across advanced emission calculations. You can sign up for this plan [here (opens in a new tab)](https://share.hsforms.com/1q7M2lfmvTWG1jos1q8tUnQbu68c)
. And in case you are interested in large-scale usage of the integration, please [reach out to our team (opens in a new tab)](https://www.climatiq.io/contact-us)
.
Functions[](#functions)
------------------------
There are three sets of functions available:
* **Estimations:** Easily calculate the emissions for different kinds of business activities, e.g. travel, shipping and energy usage based on detailed methodologies
* **Autopilot:** Leverage Climatiq's [Autopilot](/docs/api-reference/autopilot)
to automate spend- and activity-based emission estimates
* **Search:** Look up emission factors, support regions, fuel types, and others in Climatiq's database
### Estimations[](#estimations)
#### General Emission[](#general-emission)
Calculate the total estimated emissions produced for a particular activity, in kgCO2e, using any emission factor in the Climatiq database.
`Climatiq.Calculate(activityID; region; source; year; unit; amount; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `activityID` | ✓ | Text | An ID describing the activity that to search for. Multiple emission factors can share the same activity\_id, e.g. if they are from a different source or apply to a different region. You can search for `activity_id`s in the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
or via the search functions. |
| `region` | ✕ | Text | A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor applies. |
| `source` | ✕ | Text | Desired emission factor source. |
| `year` | ✕ | Number | Year in which the activity took place. |
| `unit` | ✓ | Text | Specific unit of the consumed amount, e.g. usd for Money, l for Volume or kg for Weight. See the full list [here](/docs/api-reference/models/parameters)
. |
| `amount` | ✓ | Number | Amount for which the emissions shall be calculated. |
| `showDetails` | ✕ | True/False | Indicates if details on the used emission factor should be shared: Name, source and ID of the used emission factor. |
**Examples** 
#### Air Travel[](#air-travel)
Calculate the total estimated emissions of air travel. The distance between the airports will be calculated using the great circle distance.
`Climatiq.Calculate_Travel_Air(start; end; flightclass; year; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `start` | ✓ | Text | Start location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `end` | ✓ | Text | Destination location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `flightclass` | ✕ | Text | Flight class, can be empty, `average`,`economy`, `business` or `first`. |
| `year` | ✕ | Number | The year in which the travel occurred. |
| `showDetails` | ✕ | True/False | Indicates if these details should also be shared: Distance, direct emissions, indirect emissions & notices. |
**Examples** 
#### Road Travel[](#road-travel)
Calculate the total estimated emissions of road travel. The distance between the locations will be calculated by considering the actual road network where possible.
`Climatiq.Calculate_Travel_Road(start; end; car_type; car_fuel; year; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `start` | ✓ | Text | Start location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `end` | ✓ | Text | Destination location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `car_type` | ✕ | Text | Size of the care. Valid values are `small`, `medium`, `large` and `average`. |
| `car_fuel` | ✕ | Text | Type of fuel used by the car. Valid values are: `petrol`, `diesel`, `hybrid` (cars with a battery that is recharged by the internal combustion engine), `plugin_hybrid` (cars with an internal combustion engine and a battery that can be plugged in), `battery` (for electric vehicles) and `average`. |
| `year` | ✕ | Number | The year in which the travel occurred. |
| `showDetails` | ✕ | True/False | Indicates if these details should also be shared: Distance, direct emissions, indirect emissions & notices. |
**Examples** 
#### Rail Travel[](#rail-travel)
Calculate the total estimated emissions of rail travel. The distance between the locations will be calculated by considering the actual rail network where possible. Otherwise the road distance will be used.
`Climatiq.Calculate_Travel_Rail(start; end; year; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `start` | ✓ | Text | Start location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `end` | ✓ | Text | Destination location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `year` | ✕ | Number | The year in which the travel occurred. |
| `showDetails` | ✕ | True/False | Indicates if these details should also be shared: Distance, direct emissions, indirect emissions & notices. |
**Examples** 
#### Travel based on Spend[](#travel-based-on-spend)
Calculate travel emissions based on spend-based data in any currency by using EXIOBASE emission factors. This calculation automatically takes inflation into account, if the year you spent the money was different than the year of the emission factor.
`Climatiq.Calculate_Travel_Spend(spend_type; currency; amount; location; year; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `spend_type` | ✓ | Text | The type of travel associated with the expenditure. Valid values are: `air`, `road`, `rail`, `sea`, and `hotel`. |
| `currency` | ✓ | Text | The currency in which the money unit is expressed. |
| `amount` | ✓ | Number | The amount of money spent. |
| `location` | ✓ | Text | The location where money was spent, can be any type of free text. |
| `year` | ✕ | Number | The year in which expenditures occurred. |
| `showDetails` | ✕ | True/False | Indicates if these details should also be shared: Distance, used emission factor name, source, region and notices. |
**Examples** 
#### Freight Shipping[](#freight-shipping)
Calculate the total estimated emissions of freight shipping. The distance between the locations will be calculated by considering the actual transport network where possible. By calling our API directly, it's also possible to specify the individual shipment legs as well as the mode of transport used.
`Climatiq.Calculate_IntermodalFreightTransport(start; end; mode; weight; weightUnit; direct; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `start` | ✓ | Text | Start location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `end` | ✓ | Text | Destination location, can be free text (Berlin), IATA Code (BER), UN-LOCODE (DE-BER) or coordinates, i.e. lat & lon (52.520008,13.404954) |
| `mode` | ✓ | Text | Main mode of transport. Valid values are: `air`, `road`, `rail` and `sea` |
| `weight` | ✓ | Number | Weight of the transported goods |
| `weightUnit` | ✓ | Text | Unit of the weight. Valid values are: `g`, `kg`, `t` (metric ton), `lb`, `ton` (US short ton). |
| `direct` | ✓ | True/False | Indicates if in case of sea, air or rail freight the road pre- and post-leg should NOT be added. |
| `showDetails` | ✕ | True/False | Indicates if there details should also be shared: Distance & route. |
**Examples** 
#### Procurement Emissions by Industry Classification Code[](#procurement-emissions-by-industry-classification-code)
Estimate the emissions for a purchase using an industry classification code to identify the type of purchased goods or service. This calculation accounts for tax, trade and transport margins using per-sector and per-country margins from EXIOBASE, if no user-supplied margins are provided. It also corrects for currency exchange rates and inflation adjustments, using rates from the UN Treasury, supplemented with per-industry inflation numbers from Eurostat. You can find details on the methodology [here](/docs/guides/understanding/procurement-spend-based-calculations)
.
`Climatiq.Calculate_Procurement_ByClassification(scheme; code; region; year; currency; amount; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `scheme` | ✓ | Text | The classification scheme used. Valid values are: `mcc`, `unspsc`, `isic4` and `nace2` |
| `code` | ✓ | Text | Specific code of the classification. Please be aware that UNSPSC is only available up to a family level, i.e. the last four digits should be 0. |
| `region` | ✓ | Text | The country in which the goods have been purchased, i.e. ideally the supplier country. Must be a 2-digit country code from [ISO-3166-1 (opens in a new tab)](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
. |
| `year` | ✓ | Number | Year of purchase |
| `currency` | ✓ | Text | Currency of spend, see all available currencies [here](/docs/guides/understanding/currency-support#supported-currencies)
. |
| `amount` | ✓ | Text | Spend amount |
| `showDetails` | ✕ | True/False | Indicates if these details about the calculation methodology should also be shared: Emission factor name, the applied margins for tax, trade, transport and inflation. |
**Examples** 
#### Procurement Emissions by Activity ID[](#procurement-emissions-by-activity-id)
Estimate the emissions for a purchase using an activity ID to identify the type of purchased goods or service. This calculation accounts for tax, trade and transport margins using per-sector and per-country margins from EXIOBASE, if no user-supplied margins are provided. It also corrects for currency exchange rates and inflation adjustments, using rates from the UN Treasury, supplemented with per-industry inflation numbers from Eurostat. You can find details on the methodology [here](/docs/guides/understanding/procurement-spend-based-calculations)
.
`Climatiq.Calculate_Procurement_ByActivityID(activity_id; region; year; currency; amount; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `activityID` | ✓ | Text | An ID describing the activity that to search for. Multiple emission factors can share the same activity\_id, e.g. if they are from a different source or apply to a different region. You can search for `activity_id`s in the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
or via the search functions. |
| `region` | ✓ | Text | The country in which the goods have been purchased, i.e. ideally the supplier country. Must be a 2-digit country code from [ISO-3166-1 (opens in a new tab)](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
. |
| `year` | ✓ | Number | Year of purchase |
| `currency` | ✓ | Text | Currency of spend, see all available currencies [here](/docs/guides/understanding/currency-support#supported-currencies)
. |
| `amount` | ✓ | Text | Spend amount |
| `showDetails` | ✕ | True/False | Indicates if these details about the calculation methodology should also be shared: Emission factor name, the applied margins for tax, trade, transport and inflation. |
**Examples** 
#### Fuel[](#fuel)
Estimate the emissions of fuel combustion. The calculation also provides details on the associated scope 3, i.e. the well-to-tank emissions. More options are available by directly calling our API.
`Climatiq.Calculate_Fuel(fuel_type; amount; amount_unit; region; year; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `fuel_type` | ✓ | Text | Type of fuel burned, e.g. biodiesel, cng, fuel\_gas, etc. You can make use of our search function to get a list of available fuel types. |
| `amount` | ✓ | Number | Amount of fuel burned. |
| `amount_unit` | ✓ | Text | Unit of provided amount |
| `region` | ✕ | Text | The country in which the fuel have been purchased. Must be the 2-digit UN code. |
| `year` | ✕ | Number | Year of the fuel consumption |
| `showDetails` | ✕ | True/False | Indicates if these details about the calculation methodology should also be shared: Overall co2e, combustion emissions, wtt emissions and notices. |
**Examples** 
#### Electricity[](#electricity)
Estimate the emissions of electricity usage. If desired, the function also provides details on the associated scope 3, i.e. the well-to-tank, transmission and distribution losses and their well-to-tank emissions. More options are available by directly calling the API - refer to the documentation for details.
`Climatiq.Calculate_Electricity(amount; region; year; connectionType; calculationType; supplier; energy_source; recs; includeScope3; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `amount` | ✓ | Number | Amount of electricity consumed in kWh. |
| `region` | ✕ | Text | The country or region in which the electricity has been consumed. Must be the 2-digit UN code. |
| `year` | ✕ | Text | Year of the electricity consumption |
| `connectionType` | ✕ | Text | Either the electricity was delivered via the "grid" or via a `direct` line. Default is `grid`. |
| `calculationType` | ✕ | Text | Indicates whether the `location-based` or `market-based` value should be returned, default is `location-based`. |
| `supplier` | ✕ | Text | Available where the region is GB or a US state, a supplier ID can be provided to use market factors for that supplier. Use the respective search function to find available suppliers. |
| `energy_source` | ✕ | Text | The source that electricity is generated from. Valid values are `renewable` or specific fuel types such as `natural_gas`, `coal`, `biomass` and `nuclear`. |
| `recs` | ✕ | Number | Quantity of RECs (Renewable Energy Certificates) to apply for market-based emission calculations. |
| `includeScope3` | ✕ | True/False | Indicates if the scope 3 emissions should be considered in the calculation, default is false. |
| `showDetails` | ✕ | True/False | Indicates if details should also be shared: Overall co2e, combustion emissions, wtt emissions and notices. |
**Examples** 
#### Cloud Computing - Virtual Machines[](#cloud-computing---virtual-machines)
Estimate the emissions for using virtual machines provided by the common cloud providers (AWS, GCP and Azure), including both the embodied emissions (meaning the emissions related to the manufacturing and disposal of the physical components, expressed per CPU hour over the expected lifetime of the hardware) and the electricity usage of the different components. More options are available by directly calling our API.
`Climatiq.Calculate_CloudVMs(vm_type; region; provider; duration; duration_unit; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `vm_type` | ✓ | Text | The specific virtual machine instance type you are using. |
| `region` | ✓ | Text | The region that is relevant for the calculation, as specified by the cloud provider. |
| `provider` | ✓ | Text | The provider used, valid values are: `aws`, `azure` and `gcp`. |
| `duration` | ✓ | Number | How long the machine is running for. |
| `duration_unit` | ✓ | Text | The unit the duration value is in. Valid values are `ms`, `s`, `m`, `h`, `day`, `year`. |
| `showDetails` | ✕ | True/False | Indicates if details about the calculation methodology should also be shared: Overall emissions, the memory usage energy emissions, the cpu usage energy emissions and the embodied emissions. |
#### CBAM[](#cbam)
Calculate total estimated emissions produced for a particular Combined Nomenclature (CN) code, for use with CBAM reporting.
`Climatiq.Calculate_CBAM(cn_code; production_region; weight; weight_unit; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `cn_code` | ✓ | Text | The combined nomenclature code for the imported goods. |
| `production_region` | ✓ | Text | The region the goods were produced in. If you specify "ROW" then this will return the EU default factors |
| `weight` | ✓ | Number | The weight of the imported goods in the defined unit. |
| `weight_unit` | ✓ | Text | Unit of the weight. Valid values are: `g`, `kg`, `t` (metric ton), `lb`, `ton` (US short ton). |
| `showDetails` | ✕ | True/False | Indicates if details should also be shared (overall co2e, estimated costs, the emission factor name, direct emissions, indirect emissions and notices). |
**Examples** 
### Autopilot[](#autopilot)
Autopilot is an AI-powered calculation endpoint designed to automate spend- and activity-based emission estimates. It uses a proprietary natural language processing (NLP) model paired with Climatiq’s scientific expertise to streamline complex emission calculations, making carbon insights accessible to non-experts.
Autopilot significantly reduces the time and manual effort spent identifying the appropriate emission factors and mapping activity data. Capable of ingesting any taxonomy and unstructured data, this feature matches raw text content to the correct emission factors and delivers accurate and compliant emission estimates.
Leveraging a built-in expert review mechanism and machine learning, Autopilot's matching algorithm consistently refines its precision. This is achieved through active feedback and continuous improvement of the underlying NLP model.
#### General Estimation[](#general-estimation)
Calculate total estimated emissions produced for a particular activity, in kgCO2e, using free-text input. The best matching emission factor will automatically be selected and used for the calculation.
`Climatiq.Autopilot(text; domain; unit; amount; year; region; region_fallback; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `text` | ✓ | Text | The free-form input text, such as an activity name, service or material name. |
| `domain` | ✓ | Text | Defines the scope of emission factors to be searched, see available domains [here](/docs/api-reference/autopilot#domains)
. |
| `unit` | ✓ | Text | Specific unit of the consumed amount, e.g. usd for Money, l for Volume or kg for Weight. See the full list [here](/docs/api-reference/autopilot#request)
. |
| `amount` | ✓ | Number | Amount for which the emissions shall be calculated. |
| `year` | ✕ | Number | Year in which the activity took place. |
| `region` | ✕ | Text | A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor should apply. |
| `region_fallback` | ✕ | True/False | Indicates if Autopilot should search in other regions, if no factor can be found for the given region. |
| `showDetails` | ✕ | True/False | Indicates if details on the used emission factor should be shared: Name, source and ID. |
**Examples** 
#### Suggest[](#suggest)
Receive a number of suggested Emission Factors for a particular input query. You can adjust the number of suggestions to return. Suggestions are ordered by the most likely match first. For each result, a suggestion ID is returned, which you can apply via the `Autopilot_EstimateSuggest` formula to calculate the respective emissions.
`Climatiq_Autopilot_Suggest(results, text, domain, unit_type, source, year, region, region_fallback, excludeEcoinvent, flatten, showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `results` | ✓ | Number | The maximum number of suggestions to receive. Autopilot will return as many suitable suggestions as it can find, up to the max number requested, or at most 20 suggestions. |
| `text` | ✓ | Text | The free-form input text, such as an activity name, service or material name. |
| `domain` | ✓ | Text | Defines the scope of emission factors to be searched, see available domains [here](/docs/api-reference/autopilot#domains)
. |
| `unit_type` | ✕ | Text | The unit types of the activity, can be Weight, Money, Volume and Number. When searching across multiple types, split them with a comma, e.g. "Money,Volume" |
| `source` | ✕ | Text | The source(s) in which should be searched in. If you search in multiple sources, split them with a comma, e.g. "BEIS,EPA,Ecoinvent" |
| `year` | ✕ | Number | Year in which the activity took place. |
| `region` | ✕ | Text | A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor should apply. |
| `region_fallback` | ✕ | True/False | Indicates if Autopilot should search in other regions, if no factor can be found for the given region. |
| `excludeEcoinvent` | ✕ | True/False | Indicates if Ecoinvent emission factors should be disregarded during the Matching |
| `flatten` | ✕ | True/False | Indicates if the calculation details of the matches should also be shared, i.e. estimated emissions and the details of the used emission factor (name, source, Climatiq UUID) |
| `showDetails` | ✕ | True/False | Indicates if details on the used emission factor should be shared: Name, source and ID. |
**Example - Flattened** 
**Example - Not Flattened** 
#### Estimate Suggest[](#estimate-suggest)
Calculate an emission estimation for an emission factor match. To calculate an emission estimation you will need to first find an emission factor using the Suggest endpoint. When you have selected an emission factor, you can request for a calculation using the suggestion ID.
`Climatiq_Autopilot_EstimateSuggest(suggestID; unit; amount; showDetails)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `suggestID` | ✓ | Text | An ID generated via the Suggest formula. |
| `unit` | ✓ | Text | Specific unit of the consumed amount, e.g. usd for Money, l for Volume or kg for Weight. See the full list [here](/docs/api-reference/autopilot#request)
. |
| `amount` | ✓ | Number | Amount for which the emissions shall be calculated. |
| `showDetails` | ✕ | True/False | Indicates if details on the used emission factor should be shared: Name, source and ID. |
**Example - Flattened** 
### Search
#### Search Emission Factors[](#search-emission-factors)
Search the emission factor database of Climatiq. Please be aware that this might only return a subset of results (depending on the number of results specified). The search works in the same way as our [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
. The function returns a table of results, so make sure the surrounding cells are empty when using this function. Depending on whether an existing Climatiq subscription to use the raw emission factors is in place, these will also be returned as part of the response. If you want to gain access to the raw emission factors, please [reach out to our team (opens in a new tab)](https://www.climatiq.io/contact-us)
.
`Climatiq.Search_EmissionFactors(query; numberOfResults; sector; category; source; region; year; unit_type; lca_stage)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `query` | ✕ | Text | A free-text query that will match ids, names, descriptions, etc. of emission factors. This uses fuzzy matching, so your query does not need to be precise. |
| `numberOfResults` | ✕ | Number | The number of results to be shared. The maximum value is 500. |
| `sector` | ✕ | Text | Filters by emission factor sector. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `category` | ✕ | Text | Filters by emission factor category. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `source` | ✕ | Text | Filters by emission factor source. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `region` | ✕ | Text | Filters by emission factor region. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `year` | ✕ | Number | Filters by applicable year. |
| `unit_type` | ✕ | Text | Filters by emission factor unit type, e.g. Money or Volume. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `lca_stage` | ✕ | Text | Filters by Life Cycle Assessment stage, e.g. well-to-tank. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
**Examples** 
#### Available Regions[](#available-regions)
Find available regions for a specific query. At least one of the parameters needs to be set.
`Climatiq.Search_Regions(query; sector; category; source)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `query` | ✕ | Text | A free-text query that will match ids, names, descriptions, etc. of emission factors. This uses fuzzy matching, so your query does not need to be precise. |
| `sector` | ✕ | Text | Filters by emission factor sector. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `category` | ✕ | Text | Filters by emission factor category. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
| `source` | ✕ | Text | Filters by emission factor source. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
**Examples** 
#### Available Electricity Suppliers[](#available-electricity-suppliers)
Find available electricity suppliers for a specific region to be used for the electricity emission estimation. Currently only available for GB and US regions.
`Climatiq.Search_AvailableElectricitySuppliers(region)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `region` | ✕ | Text | Filters by emission factor region. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
**Examples** 
#### Available Fuel Types[](#available-fuel-types)
Pulls a list of fuel types available to be used in the fuel emissions function for a specific unit type.
`Climatiq.Search_AvailableFuelTypes(unit_type)`
**Parameters**
| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `unit_type` | ✕ | Text | Filters by emission factor unit type, e.g. Money or Volume. Refer to the [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
for a list of available options. |
[Calculate Emissions from Freight Shipping (v1)](/docs/guides/tutorials/intermodal/intermodal-v1 "Calculate Emissions from Freight Shipping (v1)")
[Google Sheets Extension](/docs/guides/tutorials/google-sheets-extension "Google Sheets Extension")
---
# Autopilot Integration Guide - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Tutorials
Autopilot Integration Guide
Autopilot Integration Guide
===========================
⚠️
This integration is based on version v1-preview3 of Autopilot (the latest version). Please consider upgrading to this version if you are using an earlier version of the feature.
Use this guide to build the outline of your integration with Autopilot API. Autopilot helps you to map your data, such as purchases, component lists, and other data points to the correct emission factors within scope 3.1 of the GHG Protocol (Purchased Goods & Services).
By the end of this guide, you'll know how to:
* Receive emission factor suggestions for your data from Autopilot Suggest
* Select the most suitable emission factor for your calculation
* Calculate carbon emissions estimates using Autopilot Estimate
Before you begin[](#before-you-begin)
--------------------------------------
You must first obtain a Climatiq API key from the [Climatiq Dashboard (opens in a new tab)](https://app.climatiq.io/)
. You can read how to do this in [this guide](/docs/guides/how-tos/getting-api-key)
.
How Autopilot integrates into your application[](#how-autopilot-integrates-into-your-application)
--------------------------------------------------------------------------------------------------
In this guide, you'll learn how to integrate Autopilot's automated emission calculations into your application and map customer data to emission estimations. For example, suppose you are a SaaS platform providing emissions estimates based on your customer's procurement data. You can use Autopilot to automatically match each item to an emission factor and display a calculated CO2e estimate.
This consists of the following steps:
1. Sending your data to [Autopilot Suggest](/docs/api-reference/autopilot#suggest)
and receiving matching emission factors
2. Selecting the most suitable emission factor from the suggestion list
3. Sending an [Autopilot Estimate](/docs/api-reference/autopilot#estimate)
request using your selected emission factor to get a CO2e estimate
Below, you can see a diagram that gives you a high level overview of these steps.
### Input Data[](#input-data)
For the integration to work, you will need to have:
* Text-based input data, i.e. invoice line items, component data, or similar
* The input data should be human-readable (see examples in the table below)
* Units and respective quantities for each line item, i.e. 1 kg
* Units should be either [Weight](/docs/api-reference/models/parameters#weight)
, [Volume](/docs/api-reference/models/parameters#volume)
, [Number](/docs/api-reference/models/parameters#number)
, or [Money](/docs/api-reference/models/parameters#money)
. Read about Climatiq units [here](/docs/api-reference/models/parameters)
.
An example of good input data for Autopilot is specified below:
| Input | Tips & tricks |
| --- | --- |
| hardened rubber 9572 green | This input is clear, but in order to get a more precise match, try supplying more data about the rubber and what it is used for. |
| Disodium carbonate | Clear input without any ambiguity. |
| copper pipe 10mm | Clear input without any ambiguity, however, it’s beneficial to leave out information such as size and proprietary numbers from the input. |
| plastic; shielding film; building construction material; | Clear input. Great example of how category and overall input descriptions can give Autopilot more context. |
Get options from Autopilot Suggest[](#get-options-from-autopilot-suggest)
--------------------------------------------------------------------------
[Autopilot Suggest](/docs/api-reference/autopilot#suggest)
gives you list of emission factor suggestions for the text input you provide. You can also narrow down the results using multiple different filters.
To get a calculated estimation of carbon intensity, you will need to select one of Autopilot's emission factor suggestions. You can either provide these as options to your users or select it automatically based on the similarity score that we provide.
When you have selected the emission factor with the best fit, you will need to save its `suggestion_id` for any subsequent calls to the Autopilot Estimate endpoint.
Below, you can see a possible interaction model for your data and Climatiq's Suggest API.
### Choosing a domain[](#choosing-a-domain)
Domains allow Autopilot to fine-tune matching results and take sector specific patterns into account. Domains also filter out a number of sources by default, which allows Autopilot to narrow down the pool of options and, in some cases, increase matching quality.
In other words, Domains can improve matching quality in two ways: by changing the underlying model used and the underlying set of sources used.
You can view currently available domains in the [Autopilot API Reference](/docs/api-reference/autopilot#domains)
. By default, we recommend using the `general` domain if you have data that is diverse or is not sector specific.
You can use as many domains as you like, across multiple calls. Please note that some domains can be limited access only and will be marked as such in documentation. If you would like to have access, please [contact us (opens in a new tab)](https://www.climatiq.io/contact-us)
.
**You should use specific Autopilot domains when:**
* Your data mostly consists of items used in respective industry operations or processes
* You have items that are very specific to a certain industry, such as rare materials
* You have tried the general domain and had found that results are not fully aligned with the specifics of your data
### Using filters[](#using-filters)
Filters allow you to refine emission factor suggestions provided by Autopilot by providing additional context in the request body. These filters help narrow results to match the details of your emission-generating activity. You can check currently available filters in the [Autopilot API Reference](/docs/api-reference/autopilot)
.
As an example, filters can help you get an emission factor with a region, a relevant year, and lifecycle activity, as well as from specific sources. If you want to search for emission factors from EXIOBASE, include EXIOBASE in the `source` field of your request.
#### Selecting a filter option[](#selecting-a-filter-option)
Some filter options are restricted by the domain that you are using with Autopilot. For example, the `manufacturing` domain contains a subset of sources from the Climatiq database. This means that you can only include or exclude sources from this list of sources. See the [Domains](/docs/api-reference/autopilot#domains)
section for a list of sources available in each domain.
Similarly, only a subset of lifecycle activities are available in each domain. If you have indicated a LCA activity that is _not_ available for the domain you have specified, the API will return a list of available `source_lca_activity` to you for this particular domain. For a full list of `source_lca_activity`, see [this guide on using LCA activities with Climatiq (opens in a new tab)](https://www.climatiq.io/docs/guides/tutorials/lca)
.
Note that applying multiple filters at the same time can sometimes lead to little to no results. When this happens, consider relaxing some of the filters you have applied to broaden the search range, or enable the `region_fallback` flag.
**You should adjust your filters when:**
* You need data for a specific LCA stage, from a specific source, or for a specific region
* You got no results back on the first try, so should query Autopilot with relaxed filters
### Using region fallback[](#using-region-fallback)
The `region` filter is useful for targeting emission factors specific to a geographical area. However, some regions may lack sufficient data, leading to limited results.
You can enable the `region_fallback` flag to receive emission factors that are less specific than the region you have specified. Set this to `true` if you're willing to accept a less specific geographical region than the one you've specified. Climatiq will then intelligently attempt to select a different region if it does not find any emission factors with the initial region.
**You should use region fallback when:**
* Your item doesn't have a good match in the region you have initially specified
* You received no results when specifying a particular region
### Using multiple units[](#using-multiple-units)
Autopilot Suggest allows you to specify one or more units when performing emission factor matching. This allows you to expand your emission factor search in case you have data in multiple units, e.g. you have both the weight and price of the item you are trying to match to an emission factor.
For example, the most suitable emission factor for your data might be associated with the `Money` unit (e.g., emissions per dollar of goods). However, if you only specify `Weight` as the unit, the best match could be overlooked. This is because emission factors must use a unit of measurement to calculate emissions, e.g. a `Money` emission factor will always measure emissions per dollar of goods.
If you have data in more than one unit type available, we typically recommend including multiple units in your request and expanding the set of possible matches to increase the probability of finding a perfect emission factor.
Climatiq emission factors for activity-based estimations typically use `Weight` as the unit of input, but we also have an extensive library of `Money`, `Volume`, and other emission factors.
**You should specify multiple units in your Autopilot Suggest request when:**
* You have data covering 2+ units for one line item, e.g. both `Weight` and `Money`
* You are looking to get the best possible matches across all units and don’t need to keep the unit of your calculation outputs consistent
Select emission factor from Suggest results[](#select-emission-factor-from-suggest-results)
--------------------------------------------------------------------------------------------
After receiving Autopilot Suggest results, you need to select the best fitting emission factor to send to the Autopilot Estimate endpoint and perform a CO2e estimate.
For that, you need to perform two steps:
1. Select the emission factor either manually or automatically in your application
2. Send the `suggestion_id` of the emission factor to the Autopilot Estimate endpoint
Generally, we recommend the following workflow to select the emission factor:
### Using `suggestion_id`[](#using-suggestion_id)
Every emission factor Autopilot returns is associated with a `suggestion_id` identifier. Once you have reviewed and selected the most suitable factor from the list of suggestions, you can use this ID to make a subsequent call to the Estimate endpoint with the same factor.
Note that `suggestion_id`s do not persist across endpoint versions. An Autopilot suggestion generated in `v1-preview2` cannot be used for estimating emissions in `v1-preview3`.
### Using similarity scores[](#using-similarity-scores)
Similarity score is returned as [a separate field](/docs/api-reference/autopilot#response)
in the API. Climatiq returns suggestions ordered from most likely to least likely based on our proprietary scoring model.
Similarity scores help you decide if you should use the emission factor or not. They signal if we think that emission factor is a good match for your item and can be displayed to users to guide their decisions.
If you don’t want users to select emission factors themselves, you can automatically pick the top-rated factor from the response based on similarity scores.
We recommend to only automatically select the emission factor when the similarity score is equal to or more than 0.85. This way, you ensure that most of the mapped results make sense and that you validate any results the model is unsure about.
**You should use similarity score when:**
* You want to automatically select the emission factors for further Estimate calls
* You want to give users of your application guidelines on whether this data seems like a likely match
* You want to speed up the emission factor matching process by having an easy metric to refer to when doing emission factor match verification
Calculate emissions using Estimate[](#calculate-emissions-using-estimate)
--------------------------------------------------------------------------
After you have selected an emission factor and have stored the `suggestion_id` of the factor from the Suggest call, the next step is calculating the emissions.
To calculate the emissions of the selected activity, you need to send a request containing `suggestion_id` and a `parameter` object matching the factor's `unit_type`, along with its quantity to the Estimate endpoint. As a response, you will see the emissions estimate calculation along with metadata about the emission factor.
### Reusing emission factor matches[](#reusing-emission-factor-matches)
We recommend storing results from Suggest and Estimate. This is because as data versions get updated, different emission factors might be returned. Results may also change as we make updates and enhancements to the underlying Autopilot model to improve precision and accuracy. You may receive better emission factor matches in Suggest, and these may not match the emission factors you received in a previous request.
### Storing emission factor calculations[](#storing-emission-factor-calculations)
If it is important to you to keep a trail of your calculations, we recommend saving both the emission calculation result and the details of calculation (e.g. emission factor name, source, year, and others) in your application.
[Google Sheets Extension](/docs/guides/tutorials/google-sheets-extension "Google Sheets Extension")
[Get an API Key](/docs/guides/how-tos/getting-api-key "Get an API Key")
---
# Autopilot (preview 3) - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Autopilot (preview 3)
Autopilot (preview 3) 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 three months. Read more about API versioning at Climatiq [here](/docs/guides/understanding/api-versioning)
.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](https://www.climatiq.io/contact-us)
.
For an overview of how to integrate `v1-preview3` into your application, we have added an [Autopilot integration guide](/docs/guides/tutorials/autopilot-integration)
to guide you through the process.
To see the changes since `v1-preview2`, see our [changelog](/docs/changelogs/api-release/autopilot-v1)
.
Autopilot is an AI-powered calculation endpoint designed to automate spend- and activity-based emission estimates. It uses a proprietary natural language processing (NLP) model paired with Climatiq’s scientific expertise to streamline complex emission calculations, making carbon insights accessible to non-experts.
Autopilot significantly reduces the time and manual effort spent identifying the appropriate emission factors and mapping activity data. Capable of ingesting any taxonomy and unstructured data, this feature matches raw text content and contextual information to find the correct emission factors and delivers accurate and compliant emission estimates.
Autopilot's matching algorithm consistently refines its precision. This is achieved through active feedback and continuous improvement of the underlying NLP model.
Domains[](#domains)
--------------------
Calls to autopilot requires that the user specifies a domain. Domains represent a collection of data and model, defined for specific use cases, and restricts the sources used for matching emission factors. You can use the `source` and `exclude_source` parameters in the request body to define which sources to include or exclude, as long as they are part of the sources available for the chosen domain (see table below).
| Value | Description | Datasets | Sources |
| --- | --- | --- | --- |
| `general` | General list of materials and services | Climatiq | Circular Ecology, GEMIS, DISER, GLEC, Climate TRACE, MfE, Greenview, OEKOBAUDAT, EPA, Market Economics Limited, WRAP, EXIOBASE, BEIS, CAEP, CBAM, ecoinvent |
| `manufacturing` | List of materials and services relevant for the manufacturing industry aggregated from various sources | Climatiq | Circular Ecology, OEKOBAUDAT, BEIS, CBAM, EXIOBASE, EPA, GEMIS, Climate Trace, ecoinvent |
Suggest[](#suggest)
--------------------
POST Return a number of suggested emission factors. The Suggest endpoint finds emission factors that you can use to calculate emissions with via the [Estimate](/docs/api-reference/autopilot#estimate)
endpoint. You can adjust the number of suggestions to return, or filter the results by source, year, region, unit, or lifecycle activity. Suggestions are ranked, with the most relevant result presented first.
https://preview.api.climatiq.io/autopilot/v1-preview3/suggest
### Request[](#request)
This endpoint accepts the following parameters:
Request parametersShould be sent as a JSON object in the body
* suggestobject
Details of the emission-generating activity.
✖ Hide child attributes
* * *
suggest\[x\].textrequired string
The free-form input text, such as an activity name, service or material name.
* * *
suggest\[x\].domainrequired [domain](/docs/api-reference/autopilot#domains)
The [Domain](/docs/api-reference/autopilot#domains)
to be used for the calculation.
* * *
suggest\[x\].unit\_typearray of [unit\_types](/docs/api-reference/models/parameters#unit-types)
Default value: \[Weight, Money, Volume, Number\]
The unit types of the activity. Currently the only unit types that are supported are [Weight](/docs/api-reference/models/parameters#weight)
, [Money](/docs/api-reference/models/parameters#money)
, [Volume](/docs/api-reference/models/parameters#volume)
and [Number](/docs/api-reference/models/parameters#number)
.
Default Value
\[Weight, Money, Volume, Number\]
* * *
suggest\[x\].yearinteger
Default value: Latest year available
The year which the activity occurred. Climatiq will attempt to find an emission factor as close to this year as possible, but might not match the year entirely.
Default Value
Latest year available
* * *
suggest\[x\].regionstring
A [region code](/docs/api-reference/regions#region-code)
describing the geographic region where the activity was performed. If this is not provided, Climatiq will pick from emission factors all over the world. If this is provided, Climatiq will only find emission factors matching the supplied region, unless `region_fallback` is set.
* * *
suggest\[x\].region\_fallbackboolean
Default value: `false`
Set this to `true` if you're willing to accept a less specific geographical region than the one you've specified. Climatiq will then intelligently attempt to select a different region if it does not find any emission factors with the initial region.
Default Value
`false`
* * *
suggest\[x\].sourcearray of strings
Filters emission factors by data source. Contains the sources you want to include in your search. You can use either the `source` or `exclude_source` parameter, but not both simultaneously. Must be a source that is part of the specified [domain](/docs/api-reference/autopilot#domains)
.
* * *
suggest\[x\].exclude\_sourcearray of strings
Filters emission factors by data source. Contains the sources you want to exclude in your search. You can use either the `source` or `exclude_source` parameter, but not both simultaneously. Must be a source that is part of the specified [domain](/docs/api-reference/autopilot#domains)
.
* * *
suggest\[x\].source\_lca\_activityarray of strings
Filters emission factors by `source_lca_activity`.
* max\_suggestionsnumber
Default value: 10
The maximum number of suggestions to receive. Autopilot will return as many suitable suggestions as it can find, up to the max number requested, or at most 20 suggestions.
Default Value
10
curl --request POST \ --url https://preview.api.climatiq.io/autopilot/v1-preview3/suggest \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "suggest": { "domain": "general", "text": "Cement" }, "max_suggestions": 2}'
### Response[](#response)
The response includes a list of emission factors and details about its relevance:
Response parameters
* resultsarray
A list of emission factors for this emission-generating activity.
✖ Hide child attributes
* * *
results\[x\].suggestion\_idstring
The unique ID for this suggested activity. Receive an emission estimation using this ID with the Autopilot [Estimate endpoint](/docs/api-reference/autopilot#estimate)
.
* * *
results\[x\].emission\_factorobject
The emission factor that was used for the calculation.
✖ Hide child attributes
* * *
results\[x\].emission\_factor\[x\].namestring
Emission factor name.
* * *
results\[x\].emission\_factor\[x\].categorystring
Emission factor category.
* * *
results\[x\].emission\_factor\[x\].sectorstring
Emission factor sector.
* * *
results\[x\].emission\_factor\[x\].sourcestring
Emission factor publisher.
* * *
results\[x\].emission\_factor\[x\].source\_linkstring
Link to emission factor publisher.
* * *
results\[x\].emission\_factor\[x\].source\_datasetstring
The dataset this emission factor belongs to.
* * *
results\[x\].emission\_factor\[x\].yearnumber
The year in which the emission factor is considered most relevant, according to the source.
* * *
results\[x\].emission\_factor\[x\].year\_releasednumber
The year in which the emission factor was released by the source.
* * *
results\[x\].emission\_factor\[x\].regionstring
Geographic region to which the emission factor applies ([UN/LOCODE](https://unece.org/trade/uncefact/unlocode)
).
* * *
results\[x\].emission\_factor\[x\].region\_namestring
Geographic region to which the emission factor applies (in English).
* * *
results\[x\].emission\_factor\[x\].descriptionstring
Emission factor description.
* * *
results\[x\].emission\_factor\[x\].unitstring
The unit in which the `factor` field is expressed.
* * *
results\[x\].emission\_factor\[x\].unit\_typestring
The [Unit types](/docs/api-reference/unit-types)
that this emission factor accepts.
* * *
results\[x\].emission\_factor\[x\].source\_lca\_activitystring
Which LCA activity the emission factor corresponds to. [Read more about life cycle assessments here.](/docs/guides/tutorials/lca)
* * *
results\[x\].emission\_factor\[x\].data\_quality\_flagsarray
Any [data quality flags](/docs/guides/understanding/data-quality)
that applies to this emission factor.
* * *
results\[x\].emission\_factor\[x\].access\_typestring
Access type of the emission factor. Can be either `public` or `premium`. Public emission factors are available to all, while premium emission factors require a separate license.
* * *
results\[x\].suggestion\_detailsobject
Details about the suggested emission factor, including similarity score and confidence level.
✖ Hide child attributes
* * *
results\[x\].suggestion\_details\[x\].confidencestring
Confidence level of the matching between the input and the emission factor. Possible values are: `high`, `medium` and `low`.
* * *
results\[x\].suggestion\_details\[x\].similarity\_scorefloat
The numeric similarity score between the input and the emission factor. The number is between 0 and 1, and a higher score indicates a better match.
{ "results": [ { "suggestion_id": "giytkntbha4weljxmjstqljugqydkllbmfrdsljqga2ggylemu4wmzdfme-g4ydkolgmi2gkndcmy2timzymm4wkzrtgaydambqgaydambqgayq", "emission_factor": { "sector": "Materials and Manufacturing", "category": "Building Materials", "name": "Cement", "unit_type": "Money", "unit": "kg/usd", "source": "EPA", "source_dataset": "Supply Chain Greenhouse Gas Emission Factors v1.3", "year": 2022, "year_released": 2024, "region": "US", "region_name": "United States of America (the)", "description": "Emission intensity of supply chain (with margins i.e. cradle to shelf) in US dollars spend on: cement manufacturing. This factor is representative of the described goods or services category as defined by the 2017 version of the North American Industry Classification System (NAICS). Refer to the source for the source-specific data quality assessment. Retrieved from Supply Chain Factors Dataset v1.3.", "source_link": "https://cfpub.epa.gov/si/si_public_record_Report.cfm?dirEntryId=349324&Lab=CESER", "source_lca_activity": "cradle_to_shelf", "data_quality_flags": [], "access_type": "public" }, "suggestion_details": { "similarity_score": 0.97, "confidence": "high" } }, { "suggestion_id": "gezdoyrymfsdoljzg43geljug5swillcmq3taljuhaztozrwgrqtkobsmi-g4ydkolgmi2gkndcmy2timzymm4wkzrtgaydambqgaydambqgayq", "emission_factor": { "sector": "Materials and Manufacturing", "category": "Building Materials", "name": "Cement mortar", "unit_type": "Volume", "unit": "kg/m3", "source": "OEKOBAUDAT", "source_dataset": "OEKOBAUDAT 2023-I", "year": 2018, "year_released": 2023, "region": "DE", "region_name": "Germany", "description": "Emission intensity of cement mortar. The lifecycle assessment for modules A1-A3 includes: the extraction and processing of raw materials (A1) their transportation to the manufacturer (A2) and the actual manufacturing of the product (A3). Retrieved from the Oekobaudat database v20.19.120.", "source_link": "https://www.oekobaudat.de/en/service/downloads.html", "source_lca_activity": "cradle_to_gate", "data_quality_flags": [], "access_type": "public" }, "suggestion_details": { "similarity_score": 0.94, "confidence": "high" } } ]}
Estimate[](#estimate)
----------------------
POST Calculate an emission estimation for an emission factor match. To calculate an emission estimation you will need to first find an emission factor using the [Suggest](/docs/api-reference/autopilot#suggest)
endpoint. When you have selected an emission factor, you can request for a calculation using the following parameters.
https://preview.api.climatiq.io/autopilot/v1-preview3/suggest/estimate
⚠️
**Suggestions from v1-preview2**
Note that `suggestion_id`s from previous versions of Autopilot cannot be used in v1-preview3.
### Request[](#request-1)
Request parametersShould be sent as a JSON object in the body
* suggestion\_idrequired string
An ID from a Suggest endpoint result.
* parametersrequired [Parameters](/docs/api-reference/models/parameters)
object
Calculation parameters. Currently the only unit types that are supported are [Weight](/docs/api-reference/models/parameters#weight)
, [Money](/docs/api-reference/models/parameters#money)
, [Volume](/docs/api-reference/models/parameters#volume)
and [Number](/docs/api-reference/models/parameters#number)
. You should use the identical unit type as indicated in the metadata of your selected emission factor.
curl --request POST \ --url https://preview.api.climatiq.io/autopilot/v1-preview3/suggest/estimate \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "suggestion_id": "mqydemtghbrtillegaztsljugm2dsllbga2wcljsgfrtcobrmm3dqnbxge-ge3gcmzvgy3tmzbqgm2timbqmy4dimtegaydambqgaydambqgayq", "parameters": { "weight": 100, "weight_unit": "kg" }}'
### Response[](#response-1)
The response includes the CO2e estimate and details about the calculation.
Response parameters
* estimate[Estimation](/docs/api-reference/models/estimation#estimation)
The estimation performed returning the total CO2e value, constituent gases and more.
* source\_trail_array of [Source Data Point](/docs/api-reference/source-trail#source-data-point)
_
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about [Source Trail](/docs/api-reference/source-trail)
.
{ "estimate": { "co2e": 79.52, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Cement (CEM II 42.5)", "activity_id": "building_materials-type_cement_cem_ii_42.5", "id": "d022f8c4-d039-4349-a05a-21c181c68471", "access_type": "public", "source": "OEKOBAUDAT", "source_dataset": "OEKOBAUDAT 2023-I", "year": 2018, "region": "DE", "category": "Building Materials", "source_lca_activity": "cradle_to_gate", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 79.52, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 100, "activity_unit": "kg" }, "audit_trail": "enabled" }, "source_trail": [ { "data_category": "emission_factor", "name": "Cement (CEM II 42.5)", "source": "OEKOBAUDAT", "source_dataset": "OEKOBAUDAT 2023-I", "year": "2018", "region": "DE", "region_name": "Germany" } ]}
### Emission Factor License[](#emission-factor-license)
If you attempt to estimate with an emission factor with a `premium` access type and you do not have access to this premium dataset, an estimation will not be performed. These datasets require a separate purchase license. Contact us to obtain a license for the dataset you wish to purchase.
One-shot Estimate[](#one-shot-estimate)
----------------------------------------
POST Calculate total estimated emissions produced for an autopilot matched activity, in `kgCO2e`. All requests are performed by sending a POST request to the following endpoint.
Estimations can be performed by using free-text input. It will automatically perform an emission calculation with the best match, using the emission factor with the top similarity score from the list of factors provided in the [Suggest](/docs/api-reference/autopilot#suggest)
endpoint.
https://preview.api.climatiq.io/autopilot/v1-preview3/estimate
### Request[](#request-2)
Receive an estimation for the best emission factor match using the following parameters.
Request parametersShould be sent as a JSON object in the body
* textrequired string
The free-form input text, such as an activity name, service or material name.
* domainrequired [domain](/docs/api-reference/autopilot#domains)
One of the [Domains](/docs/api-reference/autopilot#domains)
to be used for the calculation.
* parametersrequired [Parameters](/docs/api-reference/models/parameters)
object
Calculation parameters. Currently the only unit types that are supported are [Weight](/docs/api-reference/models/parameters#weight)
, [Money](/docs/api-reference/models/parameters#money)
, [Volume](/docs/api-reference/models/parameters#volume)
and [Number](/docs/api-reference/models/parameters#number)
* yearinteger
Default value: Latest year available
The year which the activity occurred. Climatiq will attempt to find an emission factor as close to this year as possible, but might not match the year entirely.
Default Value
Latest year available
* regionstring
A [region code](/docs/api-reference/regions#region-code)
describing the geographic region where the activity was performed. If this is not provided, Climatiq will pick from emission factors all over the world. If this is provided, Climatiq will only find emission factors matching the supplied region, unless `region_fallback` is set.
* region\_fallbackboolean
Default value: `false`
Set this to `true` if you're willing to accept a less specific geographical region than the one you've specified. Climatiq will then intelligently attempt to select a different region if it does not find any emission factors with the initial region. Default is `false`
Default Value
`false`
* sourcearray of strings
Filters emission factors by data source. Contains the sources you want to include in your search. You can use either the `source` or `exclude_source` parameter, but not both simultaneously. Must be a source that is part of the specified [domain](/docs/api-reference/autopilot#domains)
.
* exclude\_sourcearray of strings
Filters emission factors by data source. Contains the sources you want to exclude in your search. You can use either the `source` or `exclude_source` parameter, but not both simultaneously. Must be a source that is part of the specified [domain](/docs/api-reference/autopilot#domains)
.
* source\_lca\_activityarray of strings
Filters emission factors by `source_lca_activity`.
curl --request POST \ --url https://preview.api.climatiq.io/autopilot/v1-preview3/estimate \ --header "Authorization: Bearer $CLIMATIQ_API_KEY" \ --data '{ "domain": "general", "text": "Steel", "parameters": { "money": 100, "money_unit": "usd" }}'
### Response[](#response-2)
The response includes the CO2e estimate and details about the calculation.
Response parameters
* estimate[Estimation](/docs/api-reference/models/estimation#estimation)
The estimation performed returning the total CO2e value, constituent gases and more.
* calculation\_detailsobject
Details about the calculation, such as confidence.
✖ Hide child attributes
* * *
calculation\_details\[x\].confidencestring
Confidence level of the matching between the input and the emission factor. Possible values are: `high`, `medium` and `low`.
* * *
calculation\_details\[x\].similarity\_scorefloat
The numeric similarity score between the input and the emission factor. The number is between 0 and 1, and a higher score indicates a better match.
* source\_trail_array of [Source Data Point](/docs/api-reference/source-trail#source-data-point)
_
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about [Source Trail](/docs/api-reference/source-trail)
.
{ "estimate": { "co2e": 47, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Cast iron and steel", "activity_id": "metals-type_cast_iron_steel", "id": "15e75a68-b485-494b-8cbc-398d417207a7", "access_type": "public", "source": "EPA", "source_dataset": "Supply Chain Factors Dataset (commodities)", "year": 2018, "region": "US", "category": "Metals", "source_lca_activity": "cradle_to_shelf", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": null, "co2e_other": 0.7, "co2": 41.3, "ch4": 0.2, "n2o": 0 }, "activity_data": { "activity_value": 100, "activity_unit": "usd" }, "audit_trail": "enabled" }, "calculation_details": { "similarity_score": 0.91, "confidence": "high" }, "source_trail": [ { "data_category": "emission_factor", "name": "Cast iron and steel", "source": "EPA", "source_dataset": "Supply Chain Factors Dataset (commodities)", "year": "2018", "region": "US", "region_name": "United States of America (the)" } ]}
#### Dry-runs[](#dry-runs)
If you attempt to estimate without suggestion using a `domain` that contains a source your API key does not have access to, the estimate will still work, but the CO2e values will not be provided. This is so you can evaluate how good matches would be using different domains and sources, before purchasing commercial access to the data.
[Travel (preview)](/docs/api-reference/travel "Travel (preview)")
[Autopilot (preview 2)](/docs/api-reference/autopilot/autopilot-v1-preview2 "Autopilot (preview 2)")
---
# How to Get A Climatiq API Key - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
How-Tos
Get an API Key
How to Get A Climatiq API Key
=============================
To use the Climatiq API for CO2-equivalent emission estimation, you will need an API key, which you will have to provide for each request. You can think of the API Key as the key to our house - if you have it you can come whenever you want and read our books (they're all full of emission factors).
### Sign up[](#sign-up)
To get your API key you will have to sign up for Climatiq. You can sign up [at this link. (opens in a new tab)](https://app.climatiq.io/api/signup)
You will be prompted for a few sign up details. Fill those in and you should end up at `https://app.climatiq.io/` afterwards.
### Copy API key[](#copy-api-key)
After you've signed up, click on "API Keys" in the sidebar. Click on the "Create API Key" button and name your API Key to generate one.
The long string in the "API Key" column is your API Key. You'll have to provide that when reading the API.
### Make a request[](#make-a-request)
Grabbed the key? Continue to learn how to make your [first request](/docs/guides/tutorials/quickstart)
, or read the full [API docs](/docs/api-reference)
.
[Autopilot Integration Guide](/docs/guides/tutorials/autopilot-integration "Autopilot Integration Guide")
[Make Use Of Our Postman Collection](/docs/guides/how-tos/postman-collection "Make Use Of Our Postman Collection")
---
# Postman Collection - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
How-Tos
Make Use Of Our Postman Collection
Postman Collection
==================
Get started with using the Climatiq API in Postman by forking our [Postman collection (opens in a new tab)](https://www.postman.com/climatiq/workspace/climatiq/overview)
. To use the collection, you'll need to:
Fork Collection[](#fork-collection)
------------------------------------
### Sign in to Postman[](#sign-in-to-postman)
Open our [collection (opens in a new tab)](https://www.postman.com/climatiq/workspace/climatiq/overview)
.
### Fork the collection[](#fork-the-collection)
Click the three dots next to the collection title to view more actions. Click on **Create a fork**.
Next, you should input your personal Climatiq API key retrieved from the dashboard (for full instructions, see [Get an API Key](/docs/guides/how-tos/getting-api-key)
guide).
API Key[](#api-key)
--------------------
### Find the "Variables" tab[](#find-the-variables-tab)
The "Variables" tab can be found inside the main content window.
### Input API Key[](#input-api-key)
Insert your API key into both boxes.
### Press "Save"[](#press-save)
Remember to save the request so you can send the request with the key attached.
Send Requests[](#send-requests)
--------------------------------
You can then send requests using any of the examples in the collection. Each folder demonstrates the usage of a specific endpoint. Below you can see an example response from Postman following a successful request.
For more in-depth knowledge of how to use our API, see the full [documentation](/docs/api-reference)
. More information on how to use Postman can be found on their [learning center (opens in a new tab)](https://learning.postman.com/docs/getting-started/introduction/)
.
If you have any suggestions for what you want to see in the Postman collection, feel free to [contact us (opens in a new tab)](https://www.climatiq.io/contact-us)
.
[Get an API Key](/docs/guides/how-tos/getting-api-key "Get an API Key")
[Use Python To Interact With The Climatiq Api](/docs/guides/how-tos/using-python "Use Python To Interact With The Climatiq Api")
---
# What is an Emission Factor? - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
What an Emission Factor Is
What is an Emission Factor?
===========================
An emission factor (EF) is a coefficient that describes the rate at which a given activity releases greenhouse gases (GHGs) into the atmosphere. They are also referred to as _conversion factors, emission intensity_ and _carbon intensity_.
How Global Warming is Measured.[](#how-global-warming-is-measured)
-------------------------------------------------------------------
The most well-known greenhouse gas is CO2. It is not the only one however - methane and nitrous oxide are two other major warming gases in a long list of GHGs. Measuring the comparative impact of these is complicated by the fact that **the different gases vary both in how much they warm the atmosphere and how long they remain in the atmosphere**.
For example, nitrous oxide (N2O) has a "100-year" warming effect 265-298 times more than CO2. This relative index is called Global Warming Potential (GWP), which expresses how much warming a gas will provide over some time frame. These are typically in 20-, 100- or 500-year terms; the world uses 100-year GWP numbers to assess the climate emergency as this is the time-frame it is typically described over.
For that reason, GHG emissions are often measured in CO2e (CO2 equivalents) expressed in weight, normally kg (kilograms) or t (tonne/metric ton). This unit expresses the 100-year warming effect of a given amount of a GHG in comparison to that of CO2. In other words, **for a given amount of any GHG, CO2e expresses the amount of CO2 that would warm the atmosphere as much as the same amount of the gas in question, over a 100-year time-frame from the moment of release**.
Global Warming Potential (GWP) for the Different Greenhouse Gases[](#global-warming-potential-gwp-for-the-different-greenhouse-gases)
--------------------------------------------------------------------------------------------------------------------------------------
As CO2 is the gas that acts as a base for the relative unit, the GWP for CO2 is 1. 100-year GWPs for other gases are provided by the Intergovernmental Panel on Climate Change (IPCC) in their periodic reports, called Assessment Reports. Some examples of gases with different GWP values are presented in the following table, based on the IPCC's 4th (2007), 5th (2013) and 6th (2021) Assessment Reports:
| GHG | GWP (AR4) | GWP (AR5) | GWP (AR6) |
| --- | --- | --- | --- |
| Carbon dioxide (CO2) | 1 | 1 | 1 |
| Methane (CH4) | 25 | 28 | 27.9 |
| Nitrous oxide (N2O) | 298 | 265 | 273 |
| Chlorofluorocarbon CFC-11 | 4 675 | 4 660 | 6230 |
| Sulpherhexafluoride | 22 800 | 23 500 | 24300 |
Estimating GHG Emissions Using Emission Factors[](#estimating-ghg-emissions-using-emission-factors)
----------------------------------------------------------------------------------------------------
In order to convert an activity into CO2e, we need to provide that activity in some unit. **The EF will act as an intermediary between that activity unit, converting it into CO2e, typically expressed in kg or t.**
For example: how many kg of GHG are emitted by burning 120kg of natural gas? We first have to choose an emission factor that accepts a weight unit and calculates natural gas emissions in CO2e for that weight. There are a few of them in our [Data Explorer (opens in a new tab)](https://www.climatiq.io/data)
tool.
Let’s say that we choose [the factor released by the UK government for 2021 (opens in a new tab)](https://www.climatiq.io/data/emission-factor/3aa8c276-ab13-49d4-83e4-5eaccbe6d798)
, **a factor of 2538.48 kilograms of CO2e per metric ton (t) of natural gas combusted**. If we wanted to calculate the emissions resulting from the consumption of 120kg of natural gas, the result would be given by the following equation:
Weight of gas consumed in metric tons x 2538.48
As the factor calculates the emissions based on metric tons, we convert kg into metric tons so the final product would be:
0.12 t x 2538.48 kgCO2e/t = 304.61 kgCO2e of GHG emissions
[List Metadata and Refine Searches](/docs/guides/how-tos/search-refinement "List Metadata and Refine Searches")
[The Climatiq Activity ID](/docs/guides/understanding/what-is-an-activity-id "The Climatiq Activity ID")
---
# Interacting with the Climatiq API using Python - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
How-Tos
Use Python To Interact With The Climatiq Api
Interacting with the Climatiq API using Python
==============================================
As the Climatiq API is an HTTP-based REST API, you can use it with almost every programming language in existence - Python included!
You should always refer to the [API reference](/docs/api-reference)
for comprehensive documentation about how the API works, but included below are a few code examples that will show you how to perform different tasks in Python
The snippets expect you to have the [requests (opens in a new tab)](https://requests.readthedocs.io/en/master/)
package installed to perform HTTP requests. See [here (opens in a new tab)](https://requests.readthedocs.io/en/master/user/install/)
for installation instructions.
You will also need a Climatiq API key. See [here](/docs/guides/how-tos/getting-api-key)
if you're uncertain about how to get one.
### Searching[](#searching)
This example will show you how to use the [search endpoint](/docs/api-reference/search)
to query for the emission factors related to the electricity grid mix in Australia.
# Change this to be your API key.MY_API_KEY="INSERT YOUR API KEY HERE"
url = "https://api.climatiq.io/data/v1/search"query="grid mix"data_version = "^3"
query_params = { # Free text query can be written as the "query" parameter "query": query, "data_version": data_version, # You can also filter on region, year, source and more # "AU" is Australia "region": "AU"}
# You must always specify your AUTH token in the "Authorization" header like this.authorization_headers = {"Authorization": f"Bearer: {MY_API_KEY}"}
# This performs the request and returns the result as JSONresponse = requests.get(url, params=query_params, headers=authorization_headers).json()
# And here you can do whatever you want with the resultsprint(response)
### Estimating[](#estimating)
This is an example of how to use the [estimate endpoint](/docs/api-reference/estimate)
with Python, making an estimate for the electricity grid mix in Australia.
# Change this to be your API keyMY_API_KEY="INSERT YOUR API KEY HERE"
url = "https://api.climatiq.io/data/v1/estimate"
# The activity ID for the emission factor. You can find this via the search endpoint listed above# or via the Data Explorer.activity_id = "electricity-supply_grid-source_residual_mix"
# We have many regions with the same activity id, representing the power grid in different countries.# We'd like to get the power for Australia specifically, so we will need to specify a region.# We do this by specifying the UN location code for the region# You can also see the region for different emission factors in the data explorer.region = "AU"
# We provide a data version on which we want to base our calculation. The recommended approach# is to use the latest version.data_version = "^3"
# We must also specify how much electricity generation we would like to make the estimation for.# In this case we will do it for 100 kilowatt-hours.# Different emission factors have different requirement as to what units they support estimates for.# You can see the units supported by an emission factor in the data explorer# and find more documentation about units# in the API documentation.parameters = { "energy": 100, "energy_unit": "kWh"}
json_body = { "emission_factor": { "activity_id": activity_id, "data_version": data_version, "region": region, }, # Specify how much energy we're estimating for "parameters": parameters}
# You must always specify your AUTH token in the "Authorization" header like this.authorization_headers = {"Authorization": f"Bearer: {MY_API_KEY}"}
# We send a POST request to the estimate endpoint with a json body# and the correct authorization headers.# This line will send the request and retrieve the body as JSON.response = requests.post(url, json=json_body, headers=authorization_headers).json()
# You can now do anything you want with the responseprint(response)
### Jupyter notebooks[](#jupyter-notebooks)
You can also use Climatiq in a Jupyter notebook. See and install an example Jupyter notebook [here (opens in a new tab)](https://github.com/climatiq/examples/blob/main/notebooks/climatiq.ipynb)
* * *
Do you have any questions about using Climatiq and Python together, or would you like to see similar guides for other languages? Please [reach out (opens in a new tab)](https://www.climatiq.io/contact-us)
and let us know.
[Make Use Of Our Postman Collection](/docs/guides/how-tos/postman-collection "Make Use Of Our Postman Collection")
[List Metadata and Refine Searches](/docs/guides/how-tos/search-refinement "List Metadata and Refine Searches")
---
# Calculating Scope 3.1 Emissions with Climatiq’s Procurement Endpoint - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How You Can Calculate Scope 3.1 Emissions
Calculating Scope 3.1 Emissions with Climatiq’s Procurement Endpoint
====================================================================
⚠️
**Subscription plan required**
This is a paid feature. Please see our [pricing page](https://www.climatiq.io/pricing)
for more details.
[Spend-based emission calculations (opens in a new tab)](https://www.climatiq.io/blog/science-behind-spend-based-emission-factors)
are a common way to estimate emissions for purchased goods and services (GHG Protocol Category 3.1) when detailed activity data is not available. Popular sources of spend-based emission factors include the UK-specific BEIS, the US Environmental Protection Agency (EPA), and EXIOBASE. These sources offer valuable data for calculating carbon footprints, each with unique methodologies to cater to a variety of data availability scenarios and calculation requirements.
These datasets are often derived from large-scale economic models known as [Environmentally Extended Input-Output Models (EE IOT) (opens in a new tab)](https://www.climatiq.io/blog/science-behind-spend-based-emission-factors)
. These models account for all upstream emissions associated with a product and capture emissions from resource extraction to production and transportation. However, the methods these sources use to extract emission factors from the IOTs vary and therefore also demand different input expenditure data; for instance, while some models might need basic product prices (EXIOBASE), others may require prices as they appear on retail shelves (BEIS).
**Basic Price vs Purchaser Price**
The basic price refers to the price of a product at the factory gate. Table 1 summarizes what is included in the basing and in the purchaser price.
Table 1. What Basic and Purchaser prices include
| | Sales Tax (deductible, e.g VAT/GST) | Tax (non-deductible) | Trade Margin (Retail, Wholesale) | Freight and insurance charges (invoiced separately) |
| --- | --- | --- | --- | --- |
| [Basic Price (opens in a new tab)](https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:Basic_price) | Excluded | Excluded | Excluded | Excluded |
| [Purchaser's Price (opens in a new tab)](https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:Purchaser_price) | Excluded | Included | Included | Included |
\[Basic Price\] + \[Taxes\] + \[Trade Margin\] + \[Transportation\] = \[Purchaser’s Price\]
When using emission factors from the following datasets, several key considerations must be accounted for:
* [EPA (opens in a new tab)](https://www.climatiq.io/data/source/epa)
is specific to the US and offers Emission Factors (EFs) derived from the USEEIO model. It provides two sets of emission factors; the first is designed for use with basic prices of products at the factory gate, while the second is compatible with purchaser prices, excluding taxes. At Climatiq, we utilize the latter set of factors.
* [BEIS (opens in a new tab)](https://www.climatiq.io/data/source/beis)
is specific to expenditure in the UK. It uses basic prices.
* [EXIOBASE (opens in a new tab)](https://www.climatiq.io/data/source/exiobase)
is the most commonly used resource for spend-based emission factors. By establishing a relationship between economic activity and emissions rates, it services 200 products across 49 regions. The EFs based on EXIOBASE require the provision of expenditure data in basic prices.
Adjusting your expenditure for inflation is an important aspect to consider when using spend-based emission factors. Detailed EE MRIOT models like EXIOBASE are typically updated every few years, e.g. the current version concluding observed data in 2019. The key to maintaining accuracy in such cases lies in adjusting for inflation. By converting the expenditure values to 2019 prices, you can ensure calculation accuracy by aligning your spend data with the context in which these emission factors were developed. This inflation adjustment guarantees that the spend-based emission calculations remain robust and truthful, even when applied beyond the timeframe of the data model. Refer to the section below for details on the implementation of inflation adjustments in the Procurement endpoint.
Climatiq’s Procurement calculation endpoint: streamline calculations using EXIOBASE[](#climatiqs-procurement-calculation-endpoint-streamline-calculations-using-exiobase)
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------
As explained above, and due to the nature of the underlying EXIOBASE model, the emission factors derived from it should be applied in conjunction with spend data provided in basic prices. Practitioners often use EXIOBASE emission factors incorrectly, using the purchaser’s price (total purchase price incl. tax, trade, and transport margins) when making the conversion. This approach leads to an overestimation of calculated footprints, which can sometimes be significant.
To align your calculations to the EXIOBASE model and ensure the coherence and precision of your spend-based carbon footprint assessments, it is crucial to deduct taxes, trade margins, and freight costs from the expenditure sum, followed by an adjustment for currency-based inflation.
Climatiq has developed the [Procurement calculation endpoint (opens in a new tab)](https://www.climatiq.io/docs/api-reference/procurement)
to eliminate the need for handling these complex calculations, including inflation adjustments and determining basic prices. This endpoint streamlines the calculation of your purchased goods and services carbon footprint (GHG Protocol Category 3.1) by automatically deriving basic (factory-gate) prices, adjusting for currency conversions (based on [UN Treasury (opens in a new tab)](https://treasury.un.org/operationalrates/OperationalRates.php)
, the IRS, and the World Bank), and correcting for inflation. The endpoint provides the flexibility to provide your own margin rates in the API query, or, if unknown, to default to margins derived from EXIOBASE. This enhances the precision of your spend-based emission assessments, providing a more accurate starting point for your environmental audits.
For the development of the Procurement endpoint, we collaborated with [Prof. Richard Wood (opens in a new tab)](https://www.climatiq.io/blog/welcoming-prof-richard-wood-scientific-advisory-board)
, a key developer of EXIOBASE. Prof. Wood is a member of our [scientific advisory board (opens in a new tab)](https://www.climatiq.io/blog/announcing-climatiq-scientific-advisory-board-sab)
, where he provides important guidance for further development of our solutions.
### Inflation adjustments[](#inflation-adjustments)
When applying EXIOBASE's spend-based emission factors, it's crucial to adjust for inflation. Aligning expenditure values to the year of the model's data ensures precise calculations, even when dealing with timeframes beyond the model's original scope.
The compound inflation rate, represented as the CIR (Compound Inflation Rate), reflects the cumulative inflation rates over multiple years. To calculate the inflation-adjusted spend amount, the spend should be divided by the CIR for the year following the emission factor's year (e.g., if the spend occurred in 2021 and the factor is from 2019) and then multiplied by the CIR for the year preceding the emission factor's year (e.g., if the spend occurred in 2017 and the factor is from 2019).
Our endpoint uses two sources of inflation data:
* Sector-specific inflation data: available for a number of European countries and obtained from the [European Central Bank (opens in a new tab)](https://www.ecb.europa.eu/stats/macroeconomic_and_sectoral/hicp/html/index.en.html)
.
* Country-specific inflation data: rates provided by the [World Bank (opens in a new tab)](https://www.worldbank.org/en/research/brief/inflation-database)
for those countries where sector-specific inflation rates were unavailable.
### Margin calculations[](#margin-calculations)
Climatiq’s Procurement API endpoint supports three calculation scenarios:
#### Margins unknown:[](#margins-unknown)
Where precise margins are not at hand, the API will automatically use the default EXIOBASE margins.
##### Request[](#request)
curl --request POST \--url https://api.climatiq.io/procurement/v1/spend \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "activity": { "classification_code": "12", "classification_type": "isic4" }, "spend_year": 2023, "spend_region": "DE", "money": 100, "money_unit": "eur"}'
##### Response[](#response)
{ "estimate": { "co2e": 4.562, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Tobacco products", "activity_id": "consumer_goods-type_tobacco_products", "id": "919992fc-1373-4fc9-a728-77bcfe2949d9", "access_type": "public", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": 2019, "region": "DE", "category": "Food/Beverages/Tobacco", "source_lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 4.562, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 16.55, "activity_unit": "eur" }, "audit_trail": "enabled" }, "calculation_details": { "tax_margin": 0.6744582649, "trade_margin": 0.1223713536, "transport_margin": 0, "inflation_applied": 0.22778602554608013 }, "notices": [], "source_trail": [ { "data_category": null, "name": "Average tax margins for spend type", "source": "EXIOBASE", "source_dataset": null, "year": null, "region": "DE", "region_name": "Germany" }, { "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": "Tobacco products", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": "2019", "region": "DE", "region_name": "Germany" } ]}
#### Actual margins available:[](#actual-margins-available)
Providing precise margins (trade, tax, and transport) results in the most accurate estimation of spend-based calculations.
##### Request[](#request-1)
curl --request POST \--url https://api.climatiq.io/procurement/v1/spend \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "activity": { "classification_code": "12", "classification_type": "isic4" }, "spend_year": 2023, "spend_region": "DE", "money": 100, "money_unit": "eur", "tax_margin": 0.2, "trade_margin": 0.1, "transport_margin": 0.04}'
##### Response[](#response-1)
{ "estimate": { "co2e": 14.82, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Tobacco products", "activity_id": "consumer_goods-type_tobacco_products", "id": "919992fc-1373-4fc9-a728-77bcfe2949d9", "access_type": "public", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": 2019, "region": "DE", "category": "Food/Beverages/Tobacco", "source_lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 14.82, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 53.76, "activity_unit": "eur" }, "audit_trail": "enabled" }, "calculation_details": { "tax_margin": 0.2, "trade_margin": 0.1, "transport_margin": 0.04, "inflation_applied": 0.22778602554608013 }, "notices": [], "source_trail": [ { "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": "Tobacco products", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": "2019", "region": "DE", "region_name": "Germany" } ]}
#### Actual margins partially available:[](#actual-margins-partially-available)
Complement your incomplete data with default EXIOBASE margins to fill the gaps.
##### Request[](#request-2)
curl --request POST \--url https://api.climatiq.io/procurement/v1/spend \--header "Authorization: Bearer $CLIMATIQ_API_KEY" \--data '{ "activity": { "classification_code": "12", "classification_type": "isic4" }, "spend_year": 2023, "spend_region": "DE", "money": 100, "money_unit": "eur", "tax_margin": 0.2}'
##### Response[](#response-2)
{ "estimate": { "co2e": 15.22, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Tobacco products", "activity_id": "consumer_goods-type_tobacco_products", "id": "919992fc-1373-4fc9-a728-77bcfe2949d9", "access_type": "public", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": 2019, "region": "DE", "category": "Food/Beverages/Tobacco", "source_lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 15.22, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 55.19, "activity_unit": "eur" }, "audit_trail": "enabled" }, "calculation_details": { "tax_margin": 0.2, "trade_margin": 0.1223713536, "transport_margin": 0, "inflation_applied": 0.22778602554608013 }, "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": "Tobacco products", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": "2019", "region": "DE", "region_name": "Germany" } ]}
EXIOBASE margins are elements of a broad-scale economic model. They were derived from observed statistical data for the year 2007 from official governmental sources of regions. The EXIOBASE margins may, however, carry substantial uncertainties due to inconsistencies in reporting across countries, averaging of data across different industries to match the NACE industry scheme, absence of observed data, and the fact that they represent average margins across the entire economy.
While EXIOBASE margins provide a feasible solution in the absence of known data, the use of actual, specific margins when available is advisable for the most accurate carbon footprint assessments.
In practice, data on margins can often be incomplete or missing. To cater to such scenarios of data availability, our endpoint also offers the flexibility to use a default margin when specific values are unknown, and the option to override the default ones when users have known values at hand.
Note that while trade and transport margins cannot take negative values, tax margins can indeed be negative. This situation typically arises when there are subsidies applied to a specific product.
While analyzing EXIOBASE's margin data, a number of missing values and discrepancies within the data were encountered by our science team, namely margins that were either erroneous or unreflective of actual conditions, and outliers. To rectify missing data and maintain the integrity of our dataset, we filled the gaps using industry-specific averages for the particular region and industry sector associated with the emission factor. Outliers have been handled utilizing the DBSCAN algorithm. However, some residual outliers may be present in the dataset and users are encouraged to inspect the audit trail when in doubt.
[How To Work With Different Currencies](/docs/guides/understanding/currency-support "How To Work With Different Currencies")
[Data Versioning: How Climatiq Handles Updates to Emission Factors](/docs/guides/understanding/data-versioning "Data Versioning: How Climatiq Handles Updates to Emission Factors")
---
# Fuel and Energy Related Activities (FERA) or upstream / scope 3 - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How To Estimate Scope 3 Fuel and Energy Related Activities (FERA) For Electricity, Heat and Steam
Fuel and Energy Related Activities (FERA) or upstream / scope 3
===============================================================
**This guide details the background and key methodologies behind FERA / scope 3 emission calculations.**
Introduction to FERA[](#introduction-to-fera)
----------------------------------------------
Fuel and energy-related activities are the upstream (Greenhouse Gas Protocol Scope 3, category 31) emissions arising as a result of fuel combustion either directly (Scope 1) or indirectly (Scopes 2 and 3). These are:
* Mining / extracting / refining and producing the fuel (well-to-tank / WTT)
* Transporting the fuel (or energy) to the point of use (transportation & distribution / T&D)
This guidance relates specifically to FERA arising from Scope 2 (purchased electricity, heat, steam and cooling). The table below provides some examples of activities and associated emissions sources.
| Example activities | FERA emissions (Scope 3) | Example sources of emissions |
| --- | --- | --- |
| Purchased electricity used in an office or factory
Purchased heat used in an office or a factory (e.g. district heating)
Purchased steam used in a production process | Well-to-tank (WTT)
• Production of fuel used to generate electricity, heat, cooling or steam
Transportation and distribution (T&D)
• Losses from the point of generation to the point of consumption
WTT of T&D
• Production of fuel associated with T&D losses | Oil extraction and refining coal mining
Extraction of natural gas and transportation by pipeline to point of use
Conversion to gas or liquid, shipping to country of use, pipeline transportation
Electricity losses from transportation network (high voltage & generally regional) and distribution network (post-transformer, lower voltage & generally local)
Heat losses due to distribution pipework (pre-metering point or point of entry into building) and riser losses within the applicable building |
Using Climatiq to calculate FERA emissions[](#using-climatiq-to-calculate-fera-emissions)
------------------------------------------------------------------------------------------
The emission factor database ([EFDB (opens in a new tab)](https://www.climatiq.io/data)
) contains FERA emission factors for several countries including UK, USA, France and Germany that may be used directly for reporting the upstream impact of purchased energy under the Scope 2 location-based approach. These factors may also be used to report under the market-based approach in certain circumstances (see below).
Refer to the EFDB and [API guidance (opens in a new tab)](https://www.climatiq.io/docs)
for more information on how to access FERA emission factors. Private emissions factors may also be uploaded and applied (by users on our paid plans) for supplier / company specific data.
Background: How FERA is calculated for purchased electricity[](#background-how-fera-is-calculated-for-purchased-electricity)
-----------------------------------------------------------------------------------------------------------------------------
Scope 3 upstream emissions are closely linked to Scope 2 (generation) emissions. However, whereas emissions from generation depend mainly on the fuel burned, the two elements of upstream emissions are affected by other variables; well-to-tank (WTT) emissions depend on how the fuel was produced, and transmission and distribution losses (T&D) depend on grid characteristics, including its physical extent and levels of power demand.
The associated emission factors will therefore change each year even if the fuel generation mix doesn’t change. For example, the UK uses natural gas to generate electricity and in recent years has imported a greater proportion of this as liquified gas, increasing the energy used in fuel production and hence the WTT emissions factor.
### Location-based and market-based accounting 2[](#location-based-and-market-based-accounting-2)
The key accounting methodologies (e.g. the GHG Protocol) require that organizations report Scope 2 emissions under both the location- and market-based approaches. The associated Scope 3 FERA emissions are most commonly reported using only location-based factors, however, due to a lack of suitable market-based factors.
The [GHG Protocol guidance (opens in a new tab)](https://ghgprotocol.org/sites/default/files/standards_supporting/Chapter3.pdf)
gives two methods for calculating WTT emissions - the average-data method and the supplier-specific method:
* **Supplier-specific method**, which involves collecting data from electricity providers on upstream emissions (extraction, production, and transportation) of electricity consumed by the reporting company
* **Average-data method**, which involves estimating emissions by using secondary (e.g., industry average) emission factors for upstream emissions per unit of consumption (e.g., kg CO2e/kWh). The location-based approach to Scope 3 uses the average-data method. The market-based approach to Scope 3 uses a combination of both methods depending on data availability. FERA emissions factors are published by the same bodies that publish Scope 2 factors. These factors are typically expressed as kg CO2e / kWh of purchased electricity and there may be separate factors for WTT, T&D and WTT (T&D). FERA emissions are calculated by multiplying purchased electricity (as used for Scope 2) by the relevant country emissions factor:
FERA emissions (CO2e) = electricity purchased×(EFWTT+EFT&D+EFWTT-T&D)\\text{electricity purchased} \\times (EF\_{WTT} + EF\_{T\\&D} + EF\_{\\text{WTT-T\\&D}})electricity purchased×(EFWTT+EFT&D+EFWTT-T&D)
Each fuel has different WTT emissions factors due to the different methods of production (see table above). The bodies that issue emissions factors combine these factors with information on electricity generation efficiency to get the final generation WTT factors.
The overall WTT emissions factor for the reporting organization’s electricity is a weighted average of the factors for each of the fuels in the supply mix.
EFWTT(total)\=Fuel1×EFWTT(fuel1)+Fuel2×EFWTT(fuel2)+Fuel3×EFWTT(fuel3)EF\_{WTT}(total) = Fuel\_1 \\times EF\_{WTT}(fuel\_1) + Fuel\_2 \\times EF\_{WTT}(fuel\_2) + Fuel\_3 \\times EF\_{WTT}(fuel\_3)EFWTT(total)\=Fuel1×EFWTT(fuel1)+Fuel2×EFWTT(fuel2)+Fuel3×EFWTT(fuel3)
_
Where FuelnFuel\_nFueln is the share of fuel nnn in the supply mix and EFWTT(fueln)EF\_{WTT}(fuel\_n)EFWTT(fueln) is the associated emissions factor expressed as CO2e kg / kWh. EFWTTEF\_{WTT}EFWTT is 000 for zero-fuel renewable energy.
_
If the underlying emissions factors are not known then it is possible to estimate WTT emissions by multiplying Scope 2 (generation) emissions by associated WTT percentages. These are typically about 15% for natural gas and 17% for coal.
Where scope 2 generation emissions are zero or close to zero (e.g. for biomass and nuclear) the percentage-based approach will not work so emissions factors given in terms of CO2e per kWh must be used. Climatiq uses emissions factors derived from the relevant national emission factor methodology documents.
1 Emissions from FERA are reported under Category 3 of Scope 3.
2 Location-based reporting uses the local (national / regional) grid mix and market-based reporting uses the reporting organization’s contractual fuel mix taking into account any of the tariff, supplier and use of renewable energy certificates (RECS / REGOs). See the separate Climatiq Scope 2 reporting guidance.
[How to Pick an Approach for Scope 2 Emissions](/docs/guides/understanding/selecting-electricity-efs "How to Pick an Approach for Scope 2 Emissions")
[How to Calculate Emissions from Travel](/docs/guides/understanding/travel "How to Calculate Emissions from Travel")
---
# How to List Metadata and Refine Searches - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
How-Tos
List Metadata and Refine Searches
How to List Metadata and Refine Searches
========================================
**Climatiq's database boasts an extensive collection of over 40,000 emission factors that cover a plethora of regions and sources. This guide provides a step-by-step tutorial on how to enumerate all the metadata (regions, sources, etc.) available on Climatiq, and further demonstrates how to fine-tune your searches.**
The best tool at your disposal for navigating all of Climatiq's emission factors is the [`/search` endpoint](/docs/api-reference/search)
. This endpoint does not only respond with emission factors, but also the `possible_filters` object.
The `possible_filters` object lists potential filters that if added to your query will still result in valid emission factors, and we're going to be using the rest of this guide to explore how to use it. The below JSON is a truncated example of the `possible_filter` object for a search query for the activity ID `electricity-supply_grid-source_supplier_mix`. As shown, it enumerates over years, sources, regions and more.
{ "year": [ 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015, ... ], "source": [ { "source": "ADEME", "datasets": [ "Base Carbone" ] }, { "source": "BEIS", "datasets": [ "UK Government GHG Conversion Factors for Company Reporting" ] }, ... ], "region": [ { "id": "AE", "name": "United Arab Emirates" }, { "id": "AFRICA", "name": "Africa" }, { "id": "AL", "name": "Albania" }, { "id": "AM", "name": "Armenia" }, { "id": "AO", "name": "Angola" }, { "id": "AR", "name": "Argentina" }, { "id": "AT", "name": "Austria" }, { "id": "AU", "name": "Australia" }, ... ], "category": [ "Electricity" ], "sector": [ "Energy" ], "unit_type": [ "Energy" ], "source_lca_activity": [ "electricity_consumption", "electricity_generation", "electricity_generation-transmission_and_distribution", "fuel_upstream-plant_amortization-fuel_combustion-fugitive_emissions", ... ], "access_type": [ "public" ], "data_quality_flags": [ "partial_factor", "notable_methodological_variance" ]}
Listing All Values[](#listing-all-values)
------------------------------------------
If you send a search query without any additional filters, the `possible_filters` object will contain all the metadata Climatiq has to offer, such as region, source, or year. This is because in a search query where you have not applied any filters, each piece of metadata could potentially serve as a valid filter that would still yield legitimate emission factors.
As an example, for a query like the one below:
curl --request GET \ --url 'https://api.climatiq.io/data/v1/search?data_version=^3' \ --header 'Authorization: Bearer $CLIMATIQ_API_KEY'
The `possible_filters` object will enumerate all regions, sources, etc. that Climatiq can provide.
**possible\_filters only return values you have access to**
As `possible_filters` only returns metadata that will still lead to a valid emission factor when filtered on, there are two situations where Climatiq might have metadata, such as a region, that is not returned:
1. Metadata exclusive to paid datasets: Some datasets are premium and require explicit purchase, such as ecoinvent. If this dataset is not purchased on your account, ecoinvent will not appear as a source, nor will any regions that are exclusive to ecoinvent.
2. If all emission factors with a specific property have data quality issues: Climatiq by default filters out certain emission factors if [they have data quality issues](/docs/guides/understanding/data-quality)
. This means that if all emission factors for a particular source or region have data quality issues, this source or region would not appear. If you want to use emission factors with those data quality issues, you will have to [include them explicitly](/docs/guides/understanding/data-quality#querying-with-data-quality-flags)
.
Narrowing Searches: A Practical Example[](#narrowing-searches-a-practical-example)
-----------------------------------------------------------------------------------
To illustrate this process, let's consider a real-world application that assists users in obtaining emission factor data for their electricity usage. You know the activity ID you're interested in is `electricity-supply_grid-source_supplier_mix`, but you need the user to specify a region and a data source.
### Initial Search[](#initial-search)
For the initial search, let's use the specific `activity_id` mentioned above:
curl --request GET \ --url 'https://api.climatiq.io/data/v1/search?activity_id=electricity-supply_grid-source_supplier_mix&data_version=^3' \ --header 'Authorization: Bearer $CLIMATIQ_API_KEY'
By reading the returned `possible_filters`, we now have all regions where the given `activity_id` is valid. The `possible_filters` object from the API could look something like the below:
{ "year": [ 2022, 2021, ... ], "source": [ { "source": "BEIS", "datasets": [ "UK Government GHG Conversion Factors for Company Reporting" ] }, { "source": "EPA", "datasets": [ "eGRID", "GHG Emission Factors Hub" ] }, ... ], "region": [ { "id": "AE", "name": "United Arab Emirates" }, ... { "id": "ZM", "name": "Zambia" }, { "id": "ZW", "name": "Zimbabwe" } ], ...}
### Filtering by Region[](#filtering-by-region)
We can then prompt the user for what region they're interested in. Suppose the user selects 'US' as their region. We then refine the search to reflect this selection:
curl --request GET \ --url 'https://api.climatiq.io/data/v1/search?activity_id=electricity-supply_grid-source_supplier_mix®ion=US&data_version=^3' \ --header 'Authorization: Bearer $CLIMATIQ_API_KEY'
We now have the additional metadata for this region and `activity_id`. Perhaps we can see there are still multiple sources that can provide this data, and the user needs to select one. This would be the case if the `possible_filters` returned looked like this:
{ "year": [ 2022, 2021, ... ], "source": [ { "source": "BEIS", "datasets": [ "UK Government GHG Conversion Factors for Company Reporting" ] }, { "source": "EPA", "datasets": [ "eGRID", "GHG Emission Factors Hub" ] }, ... ], "region": [ { "id": "US", "name": "United States" } ], ...}
### Filtering by Source[](#filtering-by-source)
At this stage, we include the `source` in the query to further narrow down our list of results.
curl --request GET \ --url 'https://api.climatiq.io/data/v1/search?activity_id=electricity-supply_grid-source_supplier_mix®ion=US&source=EPA&data_version=^3' \ --header 'Authorization: Bearer $CLIMATIQ_API_KEY'
This final query yields a set of emission factors specific to the `activity_id` (`electricity-supply_grid-source_supplier_mix`), the selected region ('US'), and the user-selected source ('EPA').
If necessary, we could further request more information from the user (limiting their choices to what `possible_filters` says is possible). Alternatively, we could utilize the information we already have to perform a [basic estimate](/docs/api-reference/estimate)
and let Climatiq pick the most suitable emission factor from the ones left.
[Use Python To Interact With The Climatiq Api](/docs/guides/how-tos/using-python "Use Python To Interact With The Climatiq Api")
[What an Emission Factor Is](/docs/guides/understanding/what-is-an-emission-factor "What an Emission Factor Is")
---
# What Is An Activity ID? - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
The Climatiq Activity ID
What Is An Activity ID?
=======================
**Instead of searching for individual factors, the Activity ID groups similar activities together, allowing you to easily perform calculations across different years, regions, and sources**
Climatiq assigns an activity ID to every emission factor in the database. Unlike the unique Emission Factor IDs, the activity ID is not unique for each factor. Instead, a single activity ID is shared by a set of factors that account for emissions of the same type of activity, such as electricity supply from the average grid mix. This means that **an activity ID groups together emission factors describing the same activity across all regions, years, sources, LCA stages and unit types**. When calling the API, you can [use the activity ID](/docs/api-reference/models/selector#using-activity-id)
along with additional data to easily perform calculations for the same activity across years, regions, sources and more.
Simplifying emission calculations: using activity IDs to automate estimates[](#simplifying-emission-calculations-using-activity-ids-to-automate-estimates)
-----------------------------------------------------------------------------------------------------------------------------------------------------------
The primary advantage of using an Activity ID is that it streamlines the process of connecting specific activities with their corresponding emission factors.
Let's say you want to determine the electricity emissions for your offices in New York, London, Berlin, and Paris for both 2020 and 2021. Typically, you'd have to manually find the appropriate emission factor for each combination, such as average grid mix emissions in New York for both years, requiring eight separate searches. However, since all electricity emission factors for the average grid mix are grouped under one Activity ID, you only need to map it once to the correct ID — in this case, `electricity-supply_grid-source_total_supplier_mix`. By using this ID, you can easily make API calls for each consumption data point, like 800 kWh of electricity used in London in 2020, while specifying the region and year in your API request. Instead of manually searching for individual factors, the API will handle finding the relevant 2020 UK-based electricity emission factor from the database.
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_total_supplier_mix", "region": "GB", "year": 2020, "data_version": "^6" }, "parameters": { "energy": 800, "energy_unit": "kWh" }}'
Furthermore, **this approach greatly simplifies using newly published emission factors when they become available**. When emission factors for a different year is published, they will be grouped under the same activity ID. All you need to do to get the newest dataset is to call the API and specify the new year, since the ID remains consistent across multiple years.
The naming of the Activity ID[](#the-naming-of-the-activity-id)
----------------------------------------------------------------
The ID attempts to describe the activity as accurately as possible while achieving a certain level of abstraction. Therefore, some Activity IDs may appear similar but have slight differences in specifications that impact the carbon footprint. For instance, while there is the Activity ID `electricity-supply_grid-source_total_supplier_mix` for general grid mix emissions, there is also one for the residual mix, `electricity-supply_grid-source_residual_mix`.
[What an Emission Factor Is](/docs/guides/understanding/what-is-an-emission-factor "What an Emission Factor Is")
[How CO2e calculations work](/docs/guides/understanding/co2e-calculation "How CO2e calculations work")
---
# CO2e - Methods of Calculation - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How CO2e calculations work
CO2e - Methods of Calculation
=============================
Human activities don't just emit carbon dioxide (CO2) but also a variety of other greenhouse gases that heat up the atmosphere.
Emission accounting largely happens in [carbon dioxide equivalents (CO2e) (opens in a new tab)](https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:Carbon_dioxide_equivalent)
, so a way of converting the other gases into CO2e is needed. This is done by assigning each gas (referred to as "constituent gases" here) a [Global Warming Potential (opens in a new tab)](https://en.wikipedia.org/wiki/Global_warming_potential)
(GWP), which in essence means "how many kg of CO2 would one kg of this gas correspond to." You can read more about emission factors and GWP in our [introduction to emission factors.](/docs/guides/understanding/what-is-an-emission-factor)
As models and data have improved, our best guess of the Global Warming Potential of the different gases have changed. The calculation methods that used for these GWP are the [IPCC (opens in a new tab)](https://en.wikipedia.org/wiki/Intergovernmental_Panel_on_Climate_Change)
's Assessment Reports. The Assessment Reports are generally shortened to "AR", so the "4th Assessment Report" becomes "AR4"
The last three Assessment Reports released were:
* AR4 (2007)
* AR5 (2014)
* AR6 (2021)
* * *
At Climatiq we aggregate data from a wide variety of sources that use different calculation methods. We will always inform you what calculation method our calculated CO2e is based on. Take the following example of a response from the `/estimate` endpoint:
{ "co2e": 0.31875, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "constituent_gases": { "co2e_total": 0.31875, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } //... more}
You will see a `co2e_calculation_method` field, and `calculation_origin` field. You can see that this particular estimate is calculated with the methodology from the 4th Assessment Report (`ar4`), and that the CO2e has been calculated by the source.
Climatiq-calculated CO2e[](#climatiq-calculated-co2e)
------------------------------------------------------
Not all CO2e values are calculated by the source - some are calculated by Climatiq. We do this if we have enough data to provide it and the source has not provided it pre-calculated (for example, emission factors from the US Environmental Protection Agency)
An example, if the source:
* Specifies all constituent gases used for their calculations
* Uses those gases based on the `ar4` calculation method to calculate a `co2e`
Then Climatiq has enough data to also calculate CO2e with the help of the `ar5` method. You can make an estimation with the following parameters to get the more recent AR5 numbers:
// /estimate endpoint{ "emission_factor": { "activity_id": "some-activity-id", "calculation_method": "ar5" }, "parameters": { "distance": 10, "money_unit": "km" }}
And you will get the following response back
{ "co2e": 2.9658171172938, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "climatiq", "constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 2.9328720167999998, "ch4": 0.1180605261, "n2o": 0.11184681419999999 } // ... other fields}
The key differences here are that the `co2e_calculation_method` has switched to ar5, and the `co2e_calculation_origin` has gone from `source` to `climatiq`
Defaults[](#defaults)
----------------------
Climatiq tries to stay as close to the sources as possible.
This means that we will always default to providing the CO2e emission factor provided by the source, preferring the most recent calculation method if the source provides more than one.
If you want to make your own choice about which calculation methodology to use, Climatiq allows you to define `calculation_method` in all endpoints that accept a [Selector](/docs/api-reference/models/selector)
.
Possible Returned Calculation Method Values[](#possible-returned-calculation-method-values)
--------------------------------------------------------------------------------------------
The `co2e_calculation_method` field is a standard part of Climatiq's API responses. Below is a table that describes potential values for this field across Climatiq endpoints.
Due to the need for backwards compatibility, there are multiple values that mean the same. You should check the documentation of the endpoint to see which version it uses or ensure your applications can recognize and handle both versions of each value.
Endpoints will always list the values it might return. Climatiq might add new values as a non-breaking change, e.g. when a new Assessment Report is released. Your application should not treat this list as exhaustive.
| Description | Older value | Newer value |
| --- | --- | --- |
| CO2 equivalents calculated over a 100-year timespan using the 4th IPCC Assessment Report (AR4). | `ar4` | `ipcc_ar4_gwp100` |
| CO2 equivalents calculated over a 100-year timespan using the 5th IPCC Assessment Report (AR5). | `ar5` | `ipcc_ar5_gwp100` |
| CO2 equivalents calculated over a 100-year timespan using the 6th IPCC Assessment Report (AR6). | `ar6` | `ipcc_ar6_gwp100` |
| CO2 equivalents calculated over a 100-year timespan using a combination of different IPCC Assessment Reports. This is used when multiple emission factors are involved and they do not align under a single report. | `mixed` | `ipcc_mixed_gwp100` |
[The Climatiq Activity ID](/docs/guides/understanding/what-is-an-activity-id "The Climatiq Activity ID")
[How Climatiq Handles Data Quality](/docs/guides/understanding/data-quality "How Climatiq Handles Data Quality")
---
# API Models - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Models
API Models
==========
The Climatiq API has models that are used across a wide variety of endpoints.
* [Selector](/docs/api-reference/models/selector)
is the model used if you're selecting an emission factor yourself. It allows you to select a specific emission factor by filtering based on sources, years, activity IDs and more.
* [Parameters](/docs/api-reference/models/parameters)
is the model used to pass parameters to the selected emission factor. This could contain e.g. money spent, energy used or fuel burned.
* [Estimation](/docs/api-reference/models/estimation)
is the model returned when the Climatiq API makes estimates.
[Authentication](/docs/api-reference/authentication "Authentication")
[Selector](/docs/api-reference/models/selector "Selector")
---
# How Climatiq handles data quality - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How Climatiq Handles Data Quality
How Climatiq handles data quality
=================================
While the emission factors provided by Climatiq are calculated by government agencies and top climate scientists, the occasional error is still detected by our science and data team. That means that some emission factors these bodies publish are inaccurate, wrong, or problematic in some way.
When Climatiq, or its users (that's you!) notice these mistakes we take one of several actions:
* If the emission factor is wrong enough to be unusable we often decide to not include it at all.
* If we deem the emission factor isn't unusable or misleading, we include it in the API, but describe any issues in the `data_quality_flags` parameter that is returned in a variety of endpoints. This parameter returns a list of [data quality flags](/docs/guides/understanding/data-quality#data-quality-flags)
. In addition to any flags, details of the issue will be included in the `description` field of the emission factor, which you can retrieve when [searching emission factors](/docs/api-reference/search)
.
* The decision between these two approaches is made by carefully weighing up the potential impact of the application of an erroneous factor, the importance of adhering to the source data provided, and an assessment of how best to inform users of the issue.
An example of a response after performing an estimate with an emission factor that has data quality issues could look like this:
{ "co2e": 1.1082, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-supply_grid-source_supplier_mix", "id": "8dcd59f9-8193-4b0c-93b2-0115949b9629", "access_type": "public", "source": "GHG Protocol", "source_dataset": "GHG Emissions Calculation Tool", "year": 2021, "region": "CN-NE", "category": "Electricity", "source_lca_activity": "electricity_generation", // This list is not empty! That means there are data quality issues with this emission factor "data_quality_flags": ["notable_methodological_variance"] }, "constituent_gases": { "co2e_total": 1.1082, "co2e_other": null, "co2": 1.1082, "ch4": 0.0, "n2o": 0.0 }, "activity_data": { "activity_value": 1.0, "activity_unit": "kWh" }, "audit_trail": "selector"}
The `data_quality_flags` attribute describes that there's something you should be mindful of when using this emission factor. If `data_quality_flags` is empty, it means that Climatiq has not detected any issues with the emission factor.
Querying with Data Quality Flags[](#querying-with-data-quality-flags)
----------------------------------------------------------------------
You can specify which data quality flags are acceptable for your use-case, via the `allowed_data_quality_flags` parameter. Most endpoints accept a list of data quality flags. Any emission factor that contains data quality flags _not_ in the list you have provided, will not be used.
E.g. if you provide `"allowed_data_quality_flags": ["erroneous_calculation", "partial_factor"]` in the `/estimate` endpoint, an emission factor with `partial_factor` could be chosen, as `partial_factor` is in the allowed list. However, an emission factor with both `["notable_methodological_variance", "erroneous_calculation"]` would not be, as `notable_methodological_variance` is not in the list of allowed data quality flags.
Data Quality Flags[](#data-quality-flags)
------------------------------------------
The table below shows the different data quality flags, and whether endpoints allow their use by default or not.
| Flag | Description | Allowed by default |
| --- | --- | --- |
| `notable_methodological_variance` | We have detected potential issues in the methodology (the method used to calculate an emission factor) behind an emission factor.
This could be because there is a generally recognized methodology for similar emission factors, and this one is different, or because the source is unclear about which methodology they use. | ✓ |
| `partial_factor` | The `co2e` value of this factor does not take into account all gases emitted from an activity; for example it may only take into account CO2 emissions from an activity and not other greenhouse gases. It has been included because the factor or source is considered important enough to make available. See the description of the factor for more information, and refer to the source for more details. | ✓ |
| `self_reported` | This data quality flag indicates that the entity cited in the ´source´ field is both the reporter of the emission factor and the producer of the emissions from which it was derived. It has not necessarily been vetted or produced by an acknowledged independent organization. | ✕ |
| `suspicious_homogeneity` | This data quality flag is given when multiple factors have a suspicious level of homogeneity (meaning there are identical CO2e values over multiple different activities). This implies that the underlying model did not have an appropriate level of granularity to create these factors and that they should be used with caution. | ✕ |
| `erroneous_calculation` | We have detected an error in how the source calculated the emission factor, however we do not deem that it will skew the results in a major way, and have judged that adherence to the source data makes it important enough to include. | ✕ |
If you need more tools to work with data quality, or you've found an emission factor that seems off, we'd [love to hear from you (opens in a new tab)](https://www.climatiq.io/contact-us)
.
[How CO2e calculations work](/docs/guides/understanding/co2e-calculation "How CO2e calculations work")
[How To Work With Different Currencies](/docs/guides/understanding/currency-support "How To Work With Different Currencies")
---
# How Climatiq handles currencies - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How To Work With Different Currencies
How Climatiq handles currencies
===============================
Climatiq has a variety of emission factors that use the amount of money spent on a given product or service to approximate how much GHG emissions are generated.
A table at the bottom of this page shows what currencies are supported by Climatiq.
There are a few extra things you need to be aware of to get the most accurate emissions out of money-based emission factors, often called spend-based emission factors. Let's dive in to some of them.
Exchange Rates[](#exchange-rates)
----------------------------------
Climatiq's emission factors are generally calculated based on _one_ currency - let's call that the source currency. This could be kg of CO2e emitted based on every US dollar spent, or kg of CO2e emitted based on every euro spent. Here, the source currency is USD or EUR respectively.
If we look at an emission factor in the [search endpoint](/docs/api-reference/search)
, we might get something like the following back. Notice in particular the unit and year.
{ "activity_id": "accommodation_type_hotel_room", "id": "1cd2252d-10b5-4734-afca-e463110235ef", "name": "Hotel room", // Notice the year here "year": 2016, "region": "GLOBAL", "region_name": "Global", "description": "Emission intensity of supply chain (purchase of service/standard good/capital good) in US dollars spend on: hotel room. Factors retrieved from the Quantis+GHG Protocol Scope 3 Calculator for the year 2016 and apply for years beyond 2016. The same emission factor applies to different types of investments in joint ventures/subsidiaries/associate companies that were not captured in Scope 1 emissions.", "unit_type": "Money", // Notice here that the unit is kg/USD "unit": "kg/usd" // More emission factor data here}
This means that this emission factor considers what emissions are generated by one dollar of money spent in 2016.
If you use this with another currency, such as euro, Climatiq will automatically use the applicable exchange rate from 2016 between EUR and USD, to determine what the correct USD amount is.
Climatiq only contains exchange rates between the currencies it supports and the US Dollar. That means that if neither the source currency nor the currency you send to the Climatiq API is USD, the exchange rates between the two currencies are calculated via the US Dollar exchange rates. The US dollar acts as what you would call a [vehicle currency (opens in a new tab)](https://www.jstor.org/stable/23352320)
.
Inflation[](#inflation)
------------------------
Spending a US dollar on something in 2016 isn't the same as spending it in 2023 - as inflation means you can purchase less per dollar.
Where spend-based factors are updated each year by the source organization we include the latest factors in the database as they are released. To limit the inaccuracy caused by inflation you should try to use sources that are as close to the time when you spent the money as possible, or manually adjust for inflation yourself.
At the moment Climatiq offers automatic correction for inflation for EXIOBASE data within the [Procurement](/docs/api-reference/procurement)
and [Travel](/docs/api-reference/travel)
features only.
Supported currencies[](#supported-currencies)
----------------------------------------------
For a complete list of currencies supported by the Climatiq API, please refer to our [API Reference page](/docs/api-reference/models/parameters#supported-currencies)
* * *
Still got questions? Are there features related to currency that you wish Climatiq supported?
Reach out to us!
[How Climatiq Handles Data Quality](/docs/guides/understanding/data-quality "How Climatiq Handles Data Quality")
[How You Can Calculate Scope 3.1 Emissions](/docs/guides/understanding/procurement-spend-based-calculations "How You Can Calculate Scope 3.1 Emissions")
---
# Data Version Guide - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
Data Versioning: How Climatiq Handles Updates to Emission Factors
Data Version Guide
==================
Climatiq implements two versioning systems: [API Versioning](/docs/guides/understanding/api-versioning)
and Data Versioning. API versioning focuses on which parameters the API accepts and returns, and how these may change over time. Data Versioning, which we’ll focus on here, deals with the changes of the underlying emission factor data.
We also have a shorter [reference page](/docs/api-reference/data-version)
if you need to select a version to use and don't need the level of understanding offered by this guide.
We have simplified how we handle data versioning based on user feedback. The previous format used a two number system: `major.minor`, and was usually seen with the same data release number for major and minor, e.g. `16.16`. For backwards compatibility reasons, this format still works, but we recommend using the new version format described in this guide.
Some deprecated fields in the API still return the old version format.
How Climatiq Changes Data and Why[](#how-climatiq-changes-data-and-why)
------------------------------------------------------------------------
The Climatiq emission factor database is continuously updated for many reasons, such as when:
* New emission factors are added.
* Existing emission factors are changed, such as when a source publishes corrections.
* Existing emission factors are changed when Climatiq performs internal restructuring by changing metadata such as `activity_id`, to provide additional context about the activity scope.
* Emission factors are deleted when a source deprecates the dataset, or our science team deprecates factors because of their poor quality. This happens rarely.
Climatiq bundles these changes up into data versions. A new data version is generally released each month, and has an ascending release number, such as `1`, `2`, `3`, etc. With each new data release, we provide a changelog of which factors were added, changed or removed. You can find our [data release changelogs here](/docs/changelogs/data-version)
.
Climatiq handles these monthly updates and addition of emission factors without disrupting existing applications with the concept of Data Versioning.
Data Versioning[](#data-versioning)
------------------------------------
When using most of the Climatiq endpoints, such as [freight](/docs/api-reference/intermodal-freight)
, [energy](/docs/api-reference/energy)
, [travel](/docs/api-reference/travel)
, [autopilot](/docs/api-reference/autopilot)
etc, data versioning is automatically handled for you.
Some endpoints allow you to query and estimate directly against the Climatiq Emission Factor Database - such as the [“Search”](/docs/api-reference/search)
and [“Basic Estimate”](/docs/api-reference/estimate)
endpoints. To use these endpoints you must specify a data version.
Climatiq allows you to select two different types of data version depending on your requirements: A fixed data version, or a dynamic data version.
### Fixed data version[](#fixed-data-version)
A fixed data version gives you a fixed, unchanging view of the underlying emission factor data.
When new emission factors are added, or existing emission factors are updated or removed, nothing changes for you, as your view of the data is fixed.
The advantage of using a fixed data version is stability - you know the emission factors you are using will not change unless you specifically take action to change it. You should select this type of data version when you want stability in the emission factors you use and if you’re okay with using older, and potentially inaccurate emission factors.
You use a fixed data version by supplying a data version number such as `1` , `2,` `13` , etc.
### Dynamic data version[](#dynamic-data-version)
A dynamic data version gives you a dynamic view of the data, where both new and old emission factors are available.
When an emission factor is updated and you are using a dynamic data version, the newest version of the emission factor will be used **if it still satisfies your query**, otherwise you will continue to use the old existing emission factor. See examples of both cases below.
💡
**Dynamic version selection example 1: A change leads to a newer data being used**
Let’s see an example where a dynamic data version automatically delivers an updated emission factor to you. You have provided a selector to the basic estimate endpoint which looks like this:
{ "activity_id": "consumer_goods-type_dairy_products", "region": "DE", "data_version": "^8"}
This finds the following emission factor:
{ "name": "Dairy products", "activity_id": "consumer_goods-type_dairy_products", "id": "2e2545eb-93b3-44cf-bc6c-11469619247b", "year": 2019, // ... more fields here}
In a later data version, the value for "year" was corrected from '2019' to '2018'.
As your query does not include any filters on year, the updated emission factor still satisfies your query, and it is used instead. You will receive the following emission factor.
{ "name": "Dairy products", "activity_id": "consumer_goods-type_dairy_products", "id": "3676a91b-ddcb-4a84-8b6f-ef18cb29a926", "year": 2018, // ... more fields here}
💡
**Dynamic version selection example 2: A change is ignored and stale data is used instead**
Let’s see an example where the activity ID has changed. Perhaps it has changed to clarify that the above emission factor is dairy products, but not including cheese. The activity ID would then have changed from `consumer_goods-type_dairy_products` to `consumer_goods-type_dairy_products_excluding_cheese`.
The updated emission factor does not satisfy your query anymore, as the activity ID does not match what you specified. In a situation like this, you will continue to use the existing non-updated version of the emission factor.
In this case, you would end up with the following (unchanged) emission factor.
{ "name": "Dairy products", "activity_id": "consumer_goods-type_dairy_products", "id": "3676a91b-ddcb-4a84-8b6f-ef18cb29a926", "year": 2018,}
We refer to older versions of more recent emission factors, as [stale data](/docs/guides/understanding/data-versioning#stale-data)
.
In these examples we are only considering one emission factor. In reality, there might be multiple other emission factors with the same activity ID, the same year and the same region. As In those cases, another emission factor might be used instead.
The advantage of using a dynamic data version is automatic usage of the latest emission factors, while remaining compatible with your application. You should select this type of data version if you don’t need stability in the emission factor used so that you can take advantage of updates.
You use a dynamic data version by supplying a caret in front of a data version number such as `^1` , `^2` , `^13` . Each dynamic data version will have access to the newest emission factors, and updating data versions only removes stale data.
### Which data version type should I use?[](#which-data-version-type-should-i-use)
We recommend using the **latest dynamic version, unless you have strong requirements that the underlying emission factors remain unchanged.** A requirement that data remains unchanged could e.g. be because you need to keep data identical across a reporting period, even at the cost of that data being out-of-date or wrong.
Here is a more in-depth comparison of how the different data versions handle different scenarios.
| | New emission factors are added | Existing emission factors are updated | Existing emission factors are deleted | Possibility of using [stale data](/docs/guides/understanding/data-versioning#stale-data)
? |
| --- | --- | --- | --- | --- |
| Fixed Data Version | No effect | No effect | No effect | Yes, the data you see does not change, so it might be out of date. |
| Dynamic Data Version | Your queries can return the new emission factors. | Your queries can return the new emission factors. If your query has to select between an older and an updated emission factor, it will select the newer. | If there is a non-deleted emission factor that satisfies your query equally well, this emission factor is used, otherwise the deleted factor continues to work. | There is less risk of using stale data, but still some, as the new data updates might be incompatible with your queries. |
### Stale Data[](#stale-data)
When an emission factor has been updated, but you continue to use an older version, we call this **stale data**, as the data is outdated.
In most cases, using stale data is not a problem, as the majority of emission factor updates do not impact how they can be used, but are minor things like:
* Updating the link to the source
* Clarifying the scope in the description
* Fixing of typos
The risk of using stale data exists no matter what data versioning type is used.
* For fixed data versions, stale data happens naturally, as your view of the data does not change, even if emission factors are updated.
* For dynamic data versions this happens when new versions of emission factors are released, but which do not satisfy your query conditions, and thus are not used, [see example 2](/docs/guides/understanding/data-versioning#dynamic-example-stale)
.
The only way to ensure you’re not using stale data is to manually update your data version.
### Updating data versions[](#updating-data-versions)
To avoid stale data and to make sure that your emissions calculations are up-to-date with the latest scientific data, we recommend you update your data version periodically, and at least yearly. There are two ways you can upgrade your data version:
**When using a fixed version**
If you are on an fixed data version such as `8`, you are using a fixed view of the data, where no modifications, deletions or updates have happened since that data version was released.
If you want to upgrade your fixed data version, you will see an entirely new view of the data. Emission factors will have been added, changed or removed. See our **Recommended upgrade process** below.
**When using a dynamic version**
If you are on a dynamic data version such as `^8`, you already have access to the latest emission factors, but you might also be using stale data.
If you want to upgrade your dynamic data version, some stale emission factors will be removed from your responses. See our **Recommended upgrade process** below.
**Recommended upgrade process**
* Refer to the [data changelog](/docs/changelogs/data-version)
for all data releases between your currently used compatible data release and the compatible data release you are upgrading to. See if there are any changes that will impact you.
* Test your application to see if it still works as expected.
Uniquely Identifying Emission Factors[](#uniquely-identifying-emission-factors)
--------------------------------------------------------------------------------
When selecting an emission factor, endpoints will generally accept either a `data_version` and additional filtering, or a `id`. If you are providing an `id` you do not need to specify a `data_version` .
This is because each version of an emission factor in the Climatiq database has a unique id (`id`). Whenever an emission factor is changed **in any way**, this `id` is changed. This means that finding an emission factor via an `id` will find a specific emission factor in history, even if newer emission factors are available.
Climatiq has both the concept of an `id` that uniquely defines an emission factor, disregarding data versions, and an `activity_id` that describes a particular type of activities. One emission factor will always have a unique `id`, but many emission factors, from different sources and covering different lifecycle segments, often share the same `activity_id`.
For emission factors that have not changed, the `id` will not change between data releases. This means that across a set of Climatiq data releases:
* Some emission factors (say for example the UK BEIS emission factor for electric cars for 2019) might be updated three times (perhaps due to methodology updates from the source) and will have three different `id`s
* Many emission factors will not have needed changes, and thus have the same `id` in each data version
Whenever Climatiq returns an `id` you can use it to uniquely identify the emission factor used.
[How You Can Calculate Scope 3.1 Emissions](/docs/guides/understanding/procurement-spend-based-calculations "How You Can Calculate Scope 3.1 Emissions")
[How API Versioning Works at Climatiq](/docs/guides/understanding/api-versioning "How API Versioning Works at Climatiq")
---
# Selector - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
[Models](/docs/api-reference/models)
Selector
Selector
========
A Selector is the model you use if you're selecting an emission factor yourself. A Selector allows you to select a specific emission factor via two distinct methods:
1. You can use an [activity ID](/docs/guides/understanding/what-is-an-activity-id)
for the particular activity you are interested in. As activity IDs can refer to multiple emission factors, you use the other metadata fields that Climatiq provides to filter down to those most suitable for your use case.
2. You can use a unique ID which will always refer to the same emission factor
### Using Activity ID[](#using-activity-id)
Emission factors can be queried by specifying a data version, an activity ID and a set of optional attributes. If more than one emission factor match the filtering criteria, the one from most recent year will be selected, followed by the most conservative (e.g. highest) if there is more than one available for the most recent year.
| Attribute | Required |
| --- | --- |
| **data\_version** _string_
The required [Data Version](/docs/api-reference/data-version-endpoint)
string for this request. | _required_ |
| **activity\_id** _string_
An ID describing the activity that to search for. Multiple emission factors can share the same `activity_id`, e.g. if they are from a different source or apply to a different region. | _required_ |
| **source** _string_
Emission factor data source name. | _optional_ |
| **source\_dataset** _string_
The name of the dataset the source published this emission factor under. | _optional_ |
| **region** _string_
A [region code](/docs/api-reference/regions#region-code)
describing the geographic region to which the emission factor applies. | |
| **region\_fallback** _boolean_
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` | _optional_ |
| **year\_fallback** _boolean_
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` | _optional_ |
| **year** _integer_
The year in which the emission factor is considered most relevant, according to the source. | _optional_ |
| **source\_lca\_activity** _string_
The [Life Cycle Assessment (LCA)](/docs/guides/tutorials/lca)
activity to which this factor is associated. | _optional_ |
| **calculation\_method** _`"ar4"`, `"ar5"` or `"ar6"`_
The calculation method that will be used to calculate the CO2e emission factor.
[Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation) | _optional_ |
| **allowed\_data\_quality\_flags** _array of strings_
A list of data quality flags that you are willing to allow for this estimate. See the guide on [data quality flags](/docs/guides/understanding/data-quality)
for more information and defaults. You can supply an empty list `[]` if you only want to accept emission factors without detected data quality issues. | _optional_ |
A selector for a specific activity, with additional filtering criteria can look like this:
"emission_factor": { "data_version": "^3", "activity_id": "electricity-supply_grid-source_production_mix", "source": "MfE", "region": "NZ", "year": 2020}
### Using ID[](#using-id)
Every emission factor has a unique ID, and if we update an emission factor in a new [data version](/docs/api-reference/data-version)
, it gets a new ID, so by using an ID as your selector, you can assure that you get consistent results. This could be useful for audit purposes.
| Attribute | Required |
| --- | --- |
| **id** _string_
An unique ID for one particular emission factor | _required_ |
| **calculation\_method** _`"ar4"`, `"ar5"` or `"ar6"`_
The calculation method that will be used to calculate the CO2e emission factor.
[Learn more about calculation methods here.](/docs/guides/understanding/co2e-calculation) | _optional_ |
A selector for one specific emission factor, using the unique id for that emission factor can look like this:
"emission_factor": { "id": "da80d5f9-7fb2-4cd7-aa45-781479499845",}
[Models](/docs/api-reference/models "Models")
[Parameters](/docs/api-reference/models/parameters "Parameters")
---
# API Versioning - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How API Versioning Works at Climatiq
API Versioning
==============
Climatiq implements two versioning systems: [Data Versioning](/docs/guides/understanding/data-versioning)
and API Versioning. Data Versioning ensures stability in underlying data, crucial for those using `data` namespace features or providing selector overrides. On this page, however, we focus on API Versioning, which deals with the parameters the API accepts and returns, and how these may change over time.
We'll explore **feature groups** and the two types of endpoints in the Climatiq API: **General Availability** (GA) and **Preview**.
Feature Groups and Versions[](#feature-groups-and-versions)
------------------------------------------------------------
Endpoints are categorized into **feature groups**, sharing a URL namespace. For instance, endpoints under `/compute/` or `/data/` belong to the `compute` or `data` feature groups, respectively.
Each feature group has a **version** in the URL, like `v1` or `v2-preview1`, making a complete URL look like `compute/v1/metadata`. Feature groups (and their endpoints) are divided into two variants based on their versioning:
* **General Availability (GA)** feature groups have versions, such as `v1` or `v2`.
* **Preview** feature groups have versions with a preview designation, such as `v1-preview1`, `v2-preview1` or `v2-preview2`.
### General Availability (GA) Endpoints[](#general-availability-ga-endpoints)
Endpoints under a **General Availability (GA)** feature group are stable, production-ready, and maintain backward compatibility. They do not introduce breaking changes. When a new GA version is released, the previous version enters a deprecation phase outlined as follows:
* **Announcement**: We announce the new version, and the deprecation of the old version. This is done in the monthly release notes.
* **One-Year Timeline**: The deprecated versions remains active for minimum one year post-announcement.
* **Regular Communication**: Through release notes, we will keep you updated on any endpoints nearing their deprecation date.
* **Direct Outreach**: When we are nearing the one-year mark, we will perform direct outreach to users still using any endpoints as a final reminder before the retirement.
* **Final Removal**: The old endpoints are officially removed after the deprecation period.
**Understanding Non-Breaking Changes**
While endpoints that are GA avoid breaking changes, they can still evolve in a variety of ways:
* Addition of new optional parameters.
* Returning new fields in the response.
* Methodological adjustments, like routing changes or updated emission factors.
This means that while your original code will continue to function, the exact results may vary over time. If consistency is important to you, you should consider storing the responses locally.
### Preview Endpoints[](#preview-endpoints)
Endpoints under a **Preview** feature group are for developers who want the newest Climatiq has to offer, even if it comes at having to adapt faster to changes. New endpoints, or new versions of existing endpoints initially appear in preview, undergoing one or more iterations before becoming a GA version.
Preview endpoints have a much shorter deprecation cycle. For this reason, accessing preview endpoints require you to contact Climatiq for access, so you can confirm you're ready to update frequently.
The deprecation process for preview endpoints is as follows:
* **Immediate Notice**: Users are informed directly about deprecation as soon as a new version is released.
* **Three-Month Notice Period**: There's typically a three-month window before endpoint removal.
* **Endpoint Deletion**: The older preview version is removed after 3 months.
Example[](#example)
--------------------
Let's explore a hypothetical scenario to illustrate this process. In this scenario, Climatiq offers an endpoint for calculating the carbon emissions of various fruits, accessible at `https://api.climatiq.io/food/v1/fruits`.
This `fruits` endpoint falls under the feature group `food` and is part of `version 1`.
Climatiq decides to modify this endpoint in a way that breaks backward compatibility - for instance, realizing the need to include fruit type for more precise calculations.
Consequently, a new `preview` endpoint is introduced at `https://preview.api.climatiq.io/food/v2-preview1/fruits`. This represents the first preview of what will eventually become the General Availability (GA) version 2.
Subsequently, it becomes clear that the endpoint also requires the country of origin for each fruit as a mandatory parameter. In response, a second preview endpoint is launched at `https://preview.api.climatiq.io/food/v2-preview2/fruits`, denoting preview version 2, of what will still eventually become GA v2. Following this release, users of `preview1` will be directly informed, with a three-month period provided for transitioning to `preview2`.
After thorough research and consideration, with no further changes anticipated for `v2-preview2`, the endpoint is advanced to its `GA` phase. This entails:
* The introduction of a new URL at `https://api.climatiq.io/food/v2/fruits`.
* Outreach to users of the `preview2` endpoint, offering a three-month window to migrate to the GA version.
* Announcement in our release notes that "Food v2" has been officially released, and that "Food v1" will remain operational for one more year.
* Direct communication with users of "Food v1" as the end of its availability approaches.
* One year after the release of "Food v2", deprecation of "Food v1".
**Multiple Endpoints in a Single Feature Group**
The example provided earlier focused on a single endpoint within the `food` feature group. However, it's common for feature groups to contain multiple endpoints. For instance, in our hypothetical scenario, the `food` feature group could also include a `/vegetables` endpoint.
It's important to note that when any endpoint within a feature group undergoes changes, all endpoints in that group are released as a new version. So, even if only the `/fruits` endpoint changes, there would also be a new version for the `/vegetables` endpoint, resulting in `food/v2/vegetables`. This new version would be identical to `food/v1/vegetables` in all aspects except for its URL.
The rationale for versioning all endpoints within a feature group together is to ensure compatibility and seamless integration. Often, you might need to use data from one endpoint as input for another within the same group. By maintaining consistent versioning across the group, we ensure that all endpoints within a version are designed to work together.
[Data Versioning: How Climatiq Handles Updates to Emission Factors](/docs/guides/understanding/data-versioning "Data Versioning: How Climatiq Handles Updates to Emission Factors")
[How to Pick an Approach for Scope 2 Emissions](/docs/guides/understanding/selecting-electricity-efs "How to Pick an Approach for Scope 2 Emissions")
---
# Audit Trail - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Audit Trail
Audit Trail ADD-ONADD-ON
========================
Audit trails provide detailed information about the emission factors used in calculations for advanced endpoints such as freight shipping, cloud computing, and classification. They can be stored with calculated emissions for future reference and audits.
The audit trail is considered enabled in any of the following scenarios:
1. The `audit_trail` feature is enabled for your project.
2. You provide a [Selector](/docs/api-reference/models/selector)
to an endpoint that supports it. This is so you can adjust your query based on the emission factor selected.
How Does the Audit Trail Affect Other Features?[](#how-does-the-audit-trail-affect-other-features)
---------------------------------------------------------------------------------------------------
Some endpoints such as [procurement](/docs/api-reference/procurement)
might have more detailed calculation breakdowns or details that are only visible if audit trail is enabled.
How Does the Audit Trail Affect Estimations?[](#how-does-the-audit-trail-affect-estimations)
---------------------------------------------------------------------------------------------
When the audit trail feature is enabled, the returned data in [Estimations](/docs/api-reference/models/estimation)
is affected as follows:
| | Feature Disabled (Default) | Feature Enabled |
| --- | --- | --- |
| **audit\_trail**
Indicates if the audit trail feature is enabled through a custom [Selector](/docs/api-reference/models/selector)
or the project settings. | `disabled` | `selector` if enabled through a provided selector, or `enabled` if enabled in project settings. |
| **emission\_factor**
Information about which emission factor was used for the calculation. | `null` | _[Used emission factor](/docs/api-reference/audit-trail#used-emission-factor)
_ |
| **constituent\_gases**
The constituent gases that make up the emission factor. | `null` | _[Constituent gases](/docs/api-reference/audit-trail#constituent-gases)
_ |
By default, audit trails are disabled for all projects. If you are using advanced endpoints and want to access the audit trail feature, please contact us for more information.
Used Emission Factor[](#used-emission-factor)
----------------------------------------------
This model provides information on the emission factor Climatiq used for your query.
| Attribute |
| --- |
| **name** _string_
Emission factor name. |
| **id** _string_
Unique ID for this emission factor. |
| **activity\_id** _string_
ID for the activity the emission factor applies to. Multiple factors can share the same `activity_id`, e.g. if they're from different sources or regions. |
| **access\_type** _string_
Data access type: `private` or `public`. Public factors are available to all, while private factors are only accessible to you. |
| **source** _string_
Emission factor publisher. |
| **source\_dataset** _string_
Dataset published by the source. |
| **year** _integer_
Most relevant year for the emission factor according to the source. |
| **region** _string_
A [region code](/docs/api-reference/regions#region-code)
that describes which geographic region the emission factor applies to. |
| **category** _string_
Emission factor category. |
| **source\_lca\_activity** _string_
Associated [Life Cycle Assessment (LCA)](/docs/guides/tutorials/lca)
activity. |
| **data\_quality\_flags** _array of strings_
List of [data quality flags](/docs/guides/understanding/data-quality)
for this emission factor. An empty list means no detected data quality issues. |
"emission_factor": { "name": "District heat and steam", "activity_id": "heat_and_steam-type_district", "id": "8b61d49c-b55d-4b74-bd2d-925fdd35379a", "access_type": "public", "source": "BEIS", "source_dataset": "UK Government GHG Conversion Factors for Company Reporting", "year": 2022, "region": "GB", "category": "Heat and Steam", "source_lca_activity": "use_phase", "data_quality_flags": []}
Constituent Gases[](#constituent-gases)
----------------------------------------
The constituent gases model explains which constituent gases the source of the data considers to be part of their calculations. Not all sources provide this data, so all the fields might be null.
The constituent gases also depend on the calculation methodology chosen. If you filter on different calculation methodologies, you might see different constituent gases. [Learn more about calculation methods and constituent gases here](/docs/guides/understanding/co2e-calculation)
| Attribute |
| --- |
| **co2e\_total** _float or null_
The total amount of GHG emitted per unit of activity expressed as kgCO2e, as reported by the source. It is null for Climatiq-performed calculations. |
| **co2e\_other** _float or null_
The total amount of GHG emitted that are not CO2, CH4 or N20 - expressed in kgCO2e emitted per unit of activity, as reported by the source. |
| **co2** _float or null_
The amount of carbon dioxide (CO2) emitted per unit of activity expressed as kgCO2, as reported by the source. |
| **ch4** _float or null_
The amount of methane (CH4) emitted per unit of activity expressed as kgCH4, as reported by the source. |
| **n2o** _float or null_
The amount of nitrous oxide (N2O) emitted per unit of activity expressed as kgN2O, as reported by the source. |
"constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 22.63, "ch4": 0.0004265, "n2o": 0.00004265}
[Estimation](/docs/api-reference/models/estimation "Estimation")
[Source Trail](/docs/api-reference/source-trail "Source Trail")
---
# Calculating Scope 3.6 Emissions with Climatiq's Travel feature - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How to Calculate Emissions from Travel
Calculating Scope 3.6 Emissions with Climatiq's Travel feature
==============================================================
Travel is a significant source of greenhouse gas emissions. Under the [Greenhouse Gas Protocol (opens in a new tab)](https://ghgprotocol.org/scope-3-calculation-guidance-2)
, Business Travel is accounted for within category 6 of the Scope 3 and covers travel (by air, rail, road, sea, and hotel stays) undertaken by employees in vehicles, e.g. aircraft, trains, and passenger cars that are not owned or operated by the reporting organization.
Choice of Method[](#choice-of-method)
--------------------------------------
As for all greenhouse gas calculations, the choice of methods depends on what data are available. The Greenhouse Gas Protocol provides a decision tree for selecting a method appropriate to the data you have at hand, reproduced below (Fig 1). According to the GHG Protocol methodology, the fuel-based method produces the most accurate results, followed by distance-based and then spend-based methods.
Fig. 1 Decision tree for selecting a calculation method based on available data
The relative magnitude and significance of emissions, the accuracy required for the purpose of emission calculations (e.g. internal decision-making or external reporting), and the level of effort required to get data should be considered when choosing the method. For example, rail travel is usually an insignificant part of total company emissions, and the spend-based approach, using readily available expenditure data, might be sufficient. However, for decision-making purposes (e.g. choosing to make a journey via rail or road), more accurate results are needed so using the fuel- or distance-based approach would be more appropriate.
Below are details for each calculation method:
* **Fuel-based Method:** The amount of consumed energy (fuel or electricity) is used to estimate combustion and generation emissions. Standard fuel or electricity emission factors are applied. Note: emissions from assets owned or operated by the reporting company would normally fall under scope 1 and scope 2 emissions.
* **Distance-based Method:** The distance traveled and mode of travel are used to estimate emissions. Distance-based emission factors are applied - either from standard datasets or calculated following Climatiq’s proprietary methodology.
* **Spend-based Method:** The amount of money spent on the travel activity or hotel accommodation is used to estimate emissions. Emission factors are derived from Environmentally Extended Multi-Regional Input-Output Tables (EE MRIOT) such as EXIOBASE (refer to our guide on [EE MRIOT (opens in a new tab)](https://www.climatiq.io/blog/science-behind-spend-based-emission-factors)
and to [Stadler et al. 2021 (opens in a new tab)](https://zenodo.org/record/5589597)
).
Climatiq’s Travel feature provides a complete toolkit tailored to your available data and desired accuracy level. The Travel feature can be used to estimate emissions from travel using distance or spend data. For estimations using the fuel-based method, refer to Climatiq’s [Estimate](/docs/api-reference/estimate)
endpoint and [Energy](/docs/api-reference/energy)
feature (see also section Fuel-based method below).
The following sections detail how these methods are implemented using Climatiq's calculation endpoints.
**A note on other travel emissions**
Scope 3 emissions are those arising in the company’s value chain, specifically from using assets (vehicles) not owned or operated by the reporting organization. This means it does cover the use of “gray fleet”, i.e. employee-owned vehicles but it excludes emissions from company-owned or operated vehicles (scopes 1 or 2). Also employee commuting, using employee-owned vehicles is covered separately in Scope 3 category 7.
Climatiq’s Travel Feature: Methodology[](#climatiqs-travel-feature-methodology)
--------------------------------------------------------------------------------
This document outlines the methodology used by Climatiq’s API to calculate carbon emissions generated from various travel activities. Refer to the API Docs to [learn more about how to use our Travel feature](/docs/api-reference/travel)
.
### General considerations[](#general-considerations)
All endpoints of the Travel feature accept either a [QueryLocation](/docs/api-reference/regions#query-location)
, [IataCodeLocation](/docs/api-reference/regions#iata-code-location)
, [UNLocodeLocation](/docs/api-reference/regions#unlocode-location)
or [CoordinateLocation](/docs/api-reference/regions#coordinate-location)
as origin and destination to compute distance or location-specific emissions.
By default, calculations correspond to emissions for one passenger and for a one-way trip. In the case of a round trip, each leg of the journey should be calculated separately. The estimated CO2e applies to the primary mode of transportation and doesn’t account for the initial and final legs of the journey, such as transportation to and from the airport or railway station. Upstream and use-phase emissions for different modes of transportation and hotel stays are included in the results, except for the night-based method for hotel stays.
[Upstream and use-phase emissions](/docs/guides/tutorials/lca)
for different modes of transportation and hotel stays are included in the results, except for the night-based method for hotel stays.
### Fuel-based method[](#fuel-based-method)
When you have actual fuel use data, using this data will give the most accurate results. To calculate emissions from fuel data, you can choose between two options: use Climatiq’s [Energy](/docs/api-reference/energy)
feature or [Estimate](/docs/api-reference/estimate)
endpoint. Climatiq’s Energy feature is a preferred choice, as it will also supply you with the automatic calculation of upstream emissions for a specific fuel type.
### Distance-based method[](#distance-based-method)
Distance-based methods provide route-specific calculation of emissions originating from air, car, train, and taxi travels from origin to destination.
#### Air Travel[](#air-travel)
The air travel endpoint calculates emissions associated when flying based on emission factors from [BEIS (opens in a new tab)](https://www.climatiq.io/data/source/beis)
1. The endpoint is designed to handle single-leg flights and categorizes them into short, medium, and long-haul flights for better accuracy. Cabin class is also taken into consideration with the option to specify whether the trip was in economy, business, or first class if known. For each flight, the following criteria are used to determine the selection of emission factor:
* **Flight Distance:** The distance between the specified origin and destination is calculated by the API, using the Great Circle Distance method (Haversine formula). This determines the appropriate “haul” for choosing the emission factor: domestic, short, or long, where:
* domestic flight is within UK or < 483km
* short-haul flight is > 483km < 3700km
* long-haul flight is > 3700km
* **Cabin Class:** Optional. This can be specified as economy, business, or first. If no cabin class is specified, the default “average” is used. The only class available for domestic flights is “average”.
* **Year.** Optional. The endpoint chooses the emission factor for the closest year.
The resulting carbon footprint automatically includes the Radiative Forcing factor, which is used to account for impacts of fuel burn in high altitudes. The multiplier in the BEIS emission factors is currently 1.9, so estimated emissions are approximately 1.9 times higher with the RF multiplier than without.
##### Upstream emissions for travel[](#upstream-emissions-for-travel)
The associated emissions factors from BEIS are used to calculate well-to tank (WTT) emissions associated with the production, transport, and distribution of fuel.
#### Car Travel[](#car-travel)
The car travel endpoint allows users to calculate route-specific emissions generated when driving between two points. The endpoint accommodates a range of car types, classified as follows:
By powertrain / car type:
* Diesel
* Petrol
* Hybrid
* BEV (Battery Electric Vehicle)
* PHEV (Plug-in Hybrid Electric Vehicle)
By engine / carsize ([see car examples here](/docs/api-reference/travel#car-sizes)
):
* Small
* Medium
* Large
* Average - if car size is not provided, the API will default to average engine size for calculations.
For cars with unspecified (unknown) fuel types, the average factor from UK BEIS will be used globally, except in the USA where the EPA provides a specific average car factor.
For petrol and diesel cars, the endpoint will default to UK BEIS emission factors for both the UK and regions outside of the UK. Emissions associated with burning a liter of petrol or diesel vary little by region (depending on driving style, road quality etc.) so the same emission factor can be used worldwide. However, for electric cars (BEV / PHEV), emissions vary based on the carbon intensity of the grid, so region-specific factors are used.
The following steps are taken to estimate emissions from BEV and PHEV cars in different regions:
**Battery Electric Vehicle (BEV):**
* Total distance (based on origin and destination) is calculated.
* Amount of kWh needed to travel this distance is calculated, based on the electricity consumption rate (kWh / km) for the specific size of BEV. These consumption rates are derived from the UK BEIS data.
* The amount of kWh is sent to Climatiq’s [Energy](/docs/api-reference/energy)
endpoint, which returns the amount of CO2e based on the grid intensity of the location-based grid mix.
**Plug-in Hybrid Electric Vehicle (PHEV):**
* Total distance (based on origin and destination) is calculated.
* Amount of kWh needed to travel this distance is calculated, based on the electricity consumption rate for the specific size of PHEV. These consumption rates are derived from the UK BEIS methodology.
* Amount of petrol in liters needed to travel this distance is calculated based on the petrol consumption rate for the specific size of PHEV (derived from the BEIS data).
* The amount of kWh and liters of petrol are sent to Climatiq’s [Energy](/docs/api-reference/energy)
endpoint, which returns the amount of CO2e based on the regional electricity emission factors and the petrol emission factor.
##### Upstream emissions for travel[](#upstream-emissions-for-travel-1)
The endpoint returns the upstream (Well-to-tank) emissions from the production, transport, and distribution of fuel, and any electricity transmission/distribution (T&D) losses.
For cars with Internal Combustion Engines, UK BEIS WTT (Well-to-tank) factors are used for all countries except for the US.The EPA doesn’t provide WTT factors for the US, so they’re estimated as a percentage ratio from the fuel combustion emission factor, using BEIS data for an average car:
% = EFWTTEF\_{WTT}EFWTT / EFfuel combustionEF\_{fuel\\;combustion}EFfuelcombustion
For BEV and PHEV cars: emissions from electricity generation, along with WTT for electricity generation, transmission and distribution losses and WTT for transmission and distribution, as well as WTT for fuels for PHEV cars are calculated by Climatiq’s [Energy](/docs/api-reference/energy)
endpoint.
#### Train Travel[](#train-travel)
The train travel endpoint calculates emissions for rail journeys between specific origins and destinations.
The distance between the origin and destination is calculated according to a routing algorithm through rail networks. We do not have full coverage of the global rail network. If data on specific rail segments is missing, we might use car routes for distance calculations instead of rail routes.
The selection of emissions factors for calculating emissions from train travel depends on the availability of suitable factors from the official governmental source for a given country. For the UK and the USA, the emission factors provided by the country’s official sources are used, i.e. BEIS and EPA respectively.
For countries where no rail emission factors are available, emissions will be calculated as a weighted average between electric and diesel train travel, based on the country's rail electrification rate.
##### Rail electrification rates[](#rail-electrification-rates)
These sources provide the average electrification rates used in our methodology for different countries inside and outside of the EU: [EUROSTAT 2021 (opens in a new tab)](https://ec.europa.eu/eurostat/databrowser/view/TTR00003/default/table?lang=en&category=rail.rail_if)
, [EUROSTAT 2021 (opens in a new tab)](https://ec.europa.eu/eurostat/databrowser/view/rail_if_electri/default/table?lang=en)
, [European Commission 2021 (opens in a new tab)](https://alternative-fuels-observatory.ec.europa.eu/transport-mode/rail#:~:text=Rail%20transport%20is%20currently%20by,is%20running%20on%20these%20lines.)
.
##### Average energy consumption for diesel and electric trains[](#average-energy-consumption-for-diesel-and-electric-trains)
Diesel or electricity (energy) consumption per passenger kilometer is based on average occupancy and average energy consumption per train at an EU level. The energy intensities are sent to Climatiq's Energy feature to estimate emissions from diesel and electric train travel. The results are weighted by the amount of travel done in each type of train to get a final emissions per passenger kilometer factor.
##### Emission factors for rail journeys[](#emission-factors-for-rail-journeys)
For the UK and US, the endpoint will default to official train travel emission factors from the governmental sources: BEIS and EPA, respectively.
For other countries, the fuel emission factor for diesel, as well as for electricity in a specific location will be determined through Climatiq’s [Energy endpoint](/docs/api-reference/energy)
.
For international rail travel, the endpoint uses the origin country for emission calculations. If the origin is in the UK or the USA, specific emission factors for these countries will be selected. For other countries, the endpoint will select the electrification rate of the origin and forward the data to Climatiq’s Energy endpoint. If emission factors for the origin country are unavailable, the destination country's electrification rates will be used. If electrification rates aren’t available for either the origin or destination, diesel train travel will be the default. This is on the assumption that diesel train travel is more prevalent in countries where no data exists.
##### Upstream emissions[](#upstream-emissions)
WTT emissions for diesel and electricity, electricity generation, and T&D (transmission and distribution) are calculated by the Energy endpoint when travel-specific factors aren’t provided by official emission factor sources.
BEIS provides emission factors for WTT separately which we use for upstream emissions calculation. The EPA provides only use\_phase emission factors. In this case, WTT emissions are estimated as a percentage ratio from the use\_phase emission factor, using BEIS emission factor for an average train:
% = EFWTTEF\_{WTT}EFWTT / EFuse phaseEF\_{use\\;phase}EFusephase
#### Taxi Journeys[](#taxi-journeys)
To calculate emissions from taxi trips, use the Car endpoints: [spend-based method](/docs/api-reference/travel#spend-based-method)
or [distance-based method](/docs/api-reference/travel#distance-based-method)
.
### Spend-based method[](#spend-based-method)
The API utilizes spend-based emissions factors from [EXIOBASE (opens in a new tab)](https://www.climatiq.io/data/source/exiobase)
to calculate the carbon footprint of travel by train, car, or air for your selected location. Note that the EXIOBASE spend-based emission factor, used for the road travel is, in fact, an average emission factor for a mix of different types of transport: urban and suburban passenger land transport, taxi operation, other passenger land transport and freight transport by road and can therefore produce results of lower accuracy. Climatiq advises to use fuel-based or distance-based method, where possible. Learn more about the science behind [spend-based emission calculations here (opens in a new tab)](https://www.climatiq.io/blog/science-behind-spend-based-emission-factors)
.
### Hotels[](#hotels)
Hotel nights are accounted for using both the activity-based method — determined by the number of nights spent in a hotel in a given region — or the spend-based method, which is based on the amount spent on a hotel stay in that region.
For the night-based method, the API applies an emission factor from the BEIS dataset corresponding to the region of your stay. The BEIS dataset covers up to 54 different regions, depending on the data release year.
For the spend-based method, the API applies EXIOBASE emission factors for hotel stays, corresponding to the region of interest. The API will also automatically apply inflation correction and currency conversions as required for spend-based calculations. Read more about the importance of inflation correction in [this guide](/docs/guides/understanding/procurement-spend-based-calculations)
.
In cases when the region of interest is not covered by BEIS or EXIOBASE, a fallback logic is applied. For the night-based method, the fall-back logic is as follows:
Specified city → Specified country → median of the same continent of the region
For the spend-based method, the following fallback logic is applied:
Specified country → Rest-of-the-World sub-region from EXIOBASE
##### Upstream emissions for hotel accommodation[](#upstream-emissions-for-hotel-accommodation)
Upstream emissions for hotel stays are accounted for only with the spend-based method, as it is a part of the emissions factor from EXIOBASE by default (read why in [this article (opens in a new tab)](https://www.climatiq.io/blog/science-behind-spend-based-emission-factors)
). BEIS emissions factors do not account for the upstream emissions related to hotel use.
1 The rationale behind using the BEIS emission factors: while these factors are based on the UK’s plane mix and occupancy rates, they offer cabin class options not found in other datasets, and cabin class significantly impacts emissions. EPA uses BEIS emission factors in their dataset for US domestic and international flights.
[How To Estimate Scope 3 Fuel and Energy Related Activities (FERA) For Electricity, Heat and Steam](/docs/guides/understanding/selecting-electricity-efs-scope-3 "How To Estimate Scope 3 Fuel and Energy Related Activities (FERA) For Electricity, Heat and Steam")
[ISO 14083 reporting with Freight](/docs/guides/understanding/freightv2-ISO14083 "ISO 14083 reporting with Freight")
---
# Freight v2 and ISO 14083 compliance - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
ISO 14083 reporting with Freight
Freight v2 and ISO 14083 compliance
===================================
Our Freight v2 endpoint is built to allow emissions estimation and reporting for freight in compliance with ISO 14083:2023.
Methodological details[](#methodological-details)
--------------------------------------------------
This page contains methodology information which can be relevant for ISO 14083 reporting.
### Shortest Feasible Distance[](#shortest-feasible-distance)
To match with the methodology of the GLEC default factors we use, we estimate the Shortest Feasible Distance (SFD) between points per transport mode.
GLECv3 p22:
> SFD represents the shortest practical route between two places taking into account the real operating conditions, such as the physical restrictions of a vehicle (e.g. weight and height), road type, topography and congestion and is typically found using route planning software. For most situations, it is the recommended approach. (It is important to keep in mind that SFD does not reflect the shortest distance if you are willing to risk shortcuts that might be unsuitable for your vehicle type or congestion typical of a city center.)
### GLEC default factors[](#glec-default-factors)
The GLEC framework allows transportation estimates to be made using the best available data - from default factors through to carrier-specific factors. The Climatiq Freight Feature uses the GLEC default factors. This means that estimates can be made with minimal information - knowing only the cargo weight, start and end points and mode of transport. It also permits comparisons to be made between modes of transport (Sea, Road, Air, Rail). In reality, emissions vary considerably according to many variables including route, vehicles used, vehicle efficiency and loading factor; each of these will be different for each carrier and may also change over time. The freight feature cannot therefore be used to compare between carriers and if the carrier reports an "actual" emissions number for your freight it will be different from the planned estimate. It is usually better to use primary data where possible, ie. calculate emissions based on fuel consumed.
### Full lifecycle emissions[](#full-lifecycle-emissions)
Our estimates by default cover transportation and transshipment at logistic hubs for intermodal cargo shipments, they cover both operational emissions and those arising during energy provision.
For transportation, we currently provide a breakdown into the operational and energy provision components, but not for hub operations.
### Rail defaults[](#rail-defaults)
In Europe and Asia, we estimate rail travel using a weighted average between diesel and electric rail factors, currently we use a 62% electrification rate in both, based on 62% of European rails being electrified according to the UIC Railway Handbook via GLECv3p88, use in Asia is permitted by the Smart Freight Centre, and we will replace this with better data when we find it. We also allow the user to specify if the fuel source as fully diesel or electric. Apart from Europe and Asia, we assume the fuel for rail transportation is always diesel.
### Road defaults[](#road-defaults)
For road we have two defaults based on the continent:
* For North America, we use the General emission factor from GLEC, or Refrigerated if the cargo is refrigerated.
* For the rest of the world, our default is an Articulated HGV, between 32-34tons running on diesel. We decided that HGV was an appropriate default vehicle type, and the emissions from this weight class differs from GLEcv3's road default factor by only 1g of CO2e/ton-km.
Road transportation might take several other forms of transport, such as getting on a ferry, or a train to go under a tunnel (car shuttles). For those our defaults picked are:
* Ferries: RoPax 2000-4999GT based on [figure 9 in this article (opens in a new tab)](https://www.researchgate.net/publication/344175713_An_Analysis_of_Basic_Parameters_of_Ro-Pax_Ships_and_Double-ended_Ferries_as_Basis_for_New_Hybrid_Ferries_Designs)
using HFO fuel
* Trains: “Truck + Trailer on train”. We use the European factor here, as we only have data on car shuttles in Europe.
* We perform the diesel/electricity split for this as noted in the rail section above.
### Sea defaults[](#sea-defaults)
By default, we assume container shipping and use factors dependent on the planned trade route.
### Air defaults[](#air-defaults)
We use “unknown” if the user does not specify the aircraft type, and we determine the short/long-haul status based on the GCD between the origin and destination.
### Refrigerated Cargo[](#refrigerated-cargo)
If you are shipping cargo that needs to be refrigerated, you can pass in the `refrigerated` parameter in the [request](/docs/api-reference/intermodal-freight#request)
`cargo` object. If you do this you will get the emissions for a supply chain where the cargo is kept refrigerated during the entire process.
The notable changes are:
* The logistics hubs will use emissions for temperature controlled logistics hubs
* An emissions factor taking refrigeration into account will be chosen for container sea and north american road and a multiplication factor (uplift) will be used for the emissions for rail and road transportation in other regions.
* No refrigeration uplift is used for air currently, as good data is not available, and we judge that refrigeration is not a large part of air freight emissions.
For road there are a few other things to note:
* For car shuttles (e.g. trucks on trains), we use the refrigerated uplifts for trains, which are equivalent to the ones for road.
* For RoPax ferries (trucks on ferries), we don’t apply an uplift to make calculations simpler. RoPax ferries are rare, and applying an uplift matching road uplifts, would only lead to a variance of 5% for the entire trip, for an average RoPax journey of 200km.
### Electric Road Freight[](#electric-road-freight)
We use GLEC energy intensity factors (e.g. kWh / km), and IEA emission factors (kg CO2e / kWh) for the country the transportation departs from. If IEA does not have emission factors available for that country, we use IEA’s global average factors.
ISO14083 requires the following disclosure with respect to estimates of emissions associated with the provision of energy:
The ISO 14083 approach recommends that the emissions associated with fuel and energy production infrastructure are included, although this is an approach which is not yet commonplace across emission factor sources.
The fuel emission factors from ecoinvent v3.9.1 issued by GLEC and used in the tool for electric rail include these emissions. IEA Electricity emission factors used for electric vehicles currently do not. We chose to use the IEA factors instead as they allow us to take into account the variation of emissions from electricity per country.
### Logistics Hubs[](#logistics-hubs)
We add logistics hubs to trips, each time the transportation mode switches, e.g. from road to sea or sea to rail, etc.
The logistics hubs are also added at the start and the end of the journey.
By default, we use the GLEC default emission factor for transshipment for logistics hubs, unless one of the transportation modes being switched to/from is container shipping, in that case we use the emission factor for maritime container terminals.
Based on whether or not the user has specified their cargo is refrigerated or not, we use the ambient temperature or the mixed/temperature-controlled emission factor variants.
We give the end-user an option to select any of the other GLEC default factors for logistics hubs, or remove the logistics hubs calculation. See the documentation here.
### Container units[](#container-units)
The emission factors we use from GLEC for container sea freight (CCWG) and logistics hub transshipment at maritime container terminals (Fraunhofer IML) are based on TEU (Twenty-foot equivalent Units) and container units respectively. We convert provided weights into TEU with an assumption of using twenty-foot containers and an average load of 10 tonnes per container GLECv3 p21.
ISO 14083 reporting requirements[](#iso-14083-reporting-requirements)
----------------------------------------------------------------------
The (ISO 14083) report is in two parts: the JSON response, and this document. The table below explains how to obtain each of the reporting points requested by the ISO standard.
### Reporting table[](#reporting-table)
The table below sets out the requirements of ISO 14083 and how they are met by the Climatiq Freight feature JSON response and the accompanying methodology.
ISO 14083:2023 permits reports to be provided at one or more levels of detail - from individual Transport Chain Elements (TCE) to the whole Transport Chain (TC). The level of detail required varies by user and use-case so Climatiq provides detailed information that users can use to meet their specific requirements. Climatiq’s API also avoids reporting back data that was provided by the user; this is to minimize the size of the interface which needs to be explained, supported and validated.
| ISO report requirement | Where to find / How to calculate |
| --- | --- |
| a) identification of the TCE(s) or transport chain(s) covered by this report | **JSON response**
The transport chain is clearly identified by the start, end and intermediate leg locations. The transport chain elements are clearly defined as i) legs, for transport operations and ii) locations for hub operations.
"type": "leg""type": "location" |
| b) a reference to this document, i.e. ISO 14083:2023 | **Methodology** |
| c) the total (operational plus energy provision) GHG emissions (_G_T); | **JSON Response**
Field `co2e` |
| d) the total (operational plus energy provision) GHG emission intensity (_g_T), specifying the type of transport activity distance used; | **JSON response / calculated by user**
**_g_T =** `co2e / tonne_km`
where `tonne_km` is the transport activity (see below) |
| f) the transport activity, specifying the type of distance used | **JSON response / calculated by user, methodology document**
**`tonne_km` =** `cargo_tonnes * distance_km`
Where `cargo_tonnes` is taken from the JSON response, making the conversion from other weight units as needed:
"cargo": { "weight": 100, "weight_unit": "kg" }
Great circle distance(GCD) is used for air and shortest feasible distance(SFD) is used for all other modes. Where the caller provides a distance, we require that it is converted to SFD using an appropriate Distance Adjustment Factor (DAF). |
| g) the hub activity | **JSON response**
The hub activity is provided in the JSON response as the `cargo_tonnes` field `cargo_tonnes` |
| h) the operational GHG emissions (_G_VO,T or _G_HEO,T); | **JSON response and methodology document**
**_G_VO:** `vehicle_operation_co2e`
**_G_HEO:** `hub_equipment_co2e`
Methodology: Note that `hub_equipment_co2e` uses the GLEC default factors which include energy provision emissions as well as operational emissions and it is not possible to split these out. |
| i) the operational GHG emission intensity (_g_VO or _g_HEO), specifying the type of transport activity distance used; | **Calculated by user from JSON response**
**_g_VO (vehicle operation intensity) =** `vehicle_operation_co2e / tonne_km`
**_g_HEO (hub equipment intensity) =** `hub_equipment_co2e / tonne_km`
where `tonne_km` is calculated as above. |
| j) the total GHG, transport activity and/or GHG emission intensities for each mode of transport and for hub operations, specifying the type of transport activity distance used, where appropriate. | **Calculated by user from JSON response**
Total greenhouse gas emissions for each mode of transport and for hub operations can be calculated by summing the emissions of TCE / leg:
e.g. emissions from sea travel:
Sum: `vehicle_co2e` for all legs where `"transport_mode": "sea"`
e.g. emissions from hub operations:
`hub_equipment_co2e` |
| 13.4 Supporting information | The additional supporting information required by ISO 14083:2023 is in the methodology. |
[How to Calculate Emissions from Travel](/docs/guides/understanding/travel "How to Calculate Emissions from Travel")
[A Quick Guide to Lifecycle Assessments](/docs/guides/understanding/lca-activity "A Quick Guide to Lifecycle Assessments")
---
# Source Trail - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Source Trail
Source Trail
============
At Climatiq, we strive to not be a black box, ensuring that your calculations are both accurate and credible. Our goal is for our calculations to be transparent enough to help you and your end-users trust the results you receive.
For straightforward requests, like those to the [Basic Estimate Endpoint](/docs/api-reference/estimate)
, providing this transparency is simple. These calculations involve direct application of specific emission factors to the activity data you provide, and so Climatiq simply returns the used emission factor.
For more complex calculations, however, a simple list of emission factors is insufficient. In these instances, Climatiq's Source Trail feature shows you the relevant emission factors and data points considered during the computation process. While this feature doesn't enable you to replicate the calculations, it does provide a window into the data involved, enhancing your confidence in the results.
**Source Trail and Audit Trail**
Source Trail is somewhat analogous to the [audit trail](/docs/api-reference/audit-trail)
feature already offered by Climatiq. The main difference lies in the intent: audit trails enable auditors to replicate calculations, whereas Source Trail offers insights into the components of the calculation without enabling replication.
Unlike the audit trail, which is an add-on feature, Source Trail is included at no extra cost for supported endpoints.
Source Data Point[](#source-data-point)
----------------------------------------
Endpoints will contain one or more lists of source data points.
Source data points detail the individual data points utilized in estimations. This information signals the credibility, recency, and relevance of the data to the users. We don’t include data for universal constants like conversion factors between pints and liters, and we don't include the numeric value of the data points.
| Attribute | Type | Description |
| --- | --- | --- |
| name | `string` or `null` | The name describing the data point. |
| source | `string` or `null` | The source of the data point, e.g., a scientific journal, research institute, or government agency. |
| source\_dataset | `string` or `null` | If the source publishes multiple datasets, this field clarififies which dataset the field comes from. This could be a dataset published by a governmental body or a research institute, or a citation of a scientific paper. |
| year\_most\_applicable | `string` or `null` | The years that the source judged their data to be most valid for. |
| region | `string` or `null` | The region code where the data point is most relevant. Note that data points may be applied outside their primary region. |
| region\_name | `string` or `null` | The full name of the `region` field. |
| data\_category | `string` or `null` | The category of the data point. Currently, this is either `null` or `"emission_factor"`. Future updates may introduce more categories. |
Consider an example of the [Business Travel Feature](/docs/api-reference/travel)
used with rail travel, with a partly electrified rail journey. To make that calculation Climatiq takes into account:
* How many kg diesel or kWh is used per passenger-km for diesel or electrified rail.
* How much of the railroad network in the traveled country is electrified
* The emission factors for diesel or electricity generation in the traveled country.
That means the endpoint will return a list of data points under `source_trail` that looks like this.
{ // ... other fields "source_trail": [ { "data_category": null, "name": "Average kg diesel used per passenger-km for diesel rail", "region": "EU", "region_name": "European Union", "source": "Fraunhofer Institute", "source_dataset": "Methodology for GHG Efficiency of Transport Modes", "year": "2020" }, { "data_category": null, "name": "Average kilowatt-hours used per passenger-km for electric rail", "region": "EU", "region_name": "European Union", "source": "Fraunhofer Institute", "source_dataset": "Methodology for GHG Efficiency of Transport Modes", "year": "2020" }, { "data_category": null, "name": "Average railroad electrification for country", "region": "DK", "region_name": "Denmark", "source": "EUROSTAT", "source_dataset": null, "year": "2021" }, { "data_category": "emission_factor", "name": "Diesel (100% mineral diesel)", "region": "GB", "region_name": "United Kingdom", "source": "BEIS", "source_dataset": "Greenhouse gas reporting: conversion factors 2023", "year": "2023" }, { "data_category": "emission_factor", "name": "Electricity supplied from grid - production mix", "region": "DK", "region_name": "Denmark", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2022" } ]}
[Audit Trail](/docs/api-reference/audit-trail "Audit Trail")
[Data Versioning](/docs/api-reference/data-version "Data Versioning")
---
# A quick guide to Lifecycle Assessments and using Climatiq for product and corporate reporting - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
A Quick Guide to Lifecycle Assessments
A quick guide to Lifecycle Assessments and using Climatiq for product and corporate reporting
=============================================================================================
Introduction[](#introduction)
------------------------------
Life cycle assessment (LCA) is a methodology for assessing the environmental impacts associated with all stages of a product, process or service.
Life cycle stages are typically split into three phases, often referred to collectively as “Cradle to Grave” or, when materials are recycled or reused, “Cradle to Cradle”.
* **Upstream:** activities that occur in the production of the goods or services represented by the emission factor that get the good or service to the point of consumption.
* Examples: growing crops, mining and refining fuels, manufacturing a good;
* **Use:** the activity associated with the direct use of the goods or services represented by the emission factor.
* Examples: burning fuels for heating and transportation, generation of electricity used to power buildings and machinery, processing limestone to make lime;
* **Downstream:** activities that occur after the upstream and use phases associated with processing, transportation or disposal of goods or services represented by the emission factor.
* Examples: using a courier to transport a finished good to a buyer, disposal of a good in landfill.
Product carbon footprints and corporate reporting[](#product-carbon-footprints-and-corporate-reporting)
--------------------------------------------------------------------------------------------------------
LCA is usually used for products, goods and services; the terms “upstream”, “downstream” and “use” above refer to the stages in a product’s life. Unless you are preparing Product Carbon Footprints or other similar LCAs for products you probably don’t need to worry about the meaning of the LCA activity terms in that context. If you are preparing LCAs then the [Greenhouse Gas Protocol Product Standard (opens in a new tab)](https://ghgprotocol.org/product-standard)
is worth reading. For other users, what is more important is where they fit into corporate reporting.
For corporate reporting under the [Greenhouse Gas Protocol (GHGP) (opens in a new tab)](https://ghgprotocol.org/companies-and-organizations)
the terms “upstream” and “downstream” refer to a company, not a good or service. They are defined by who pays for and / or provides the good or service. In general, goods and services paid for by the reporting company are upstream and those paid for by others are downstream. Upstream and downstream emissions are within GHGP scope 3. Of the fifteen scope 3 categories, the first eight (e.g. purchased goods and services) are upstream from the company and the last seven (e.g. use of sold products, end of life) are downstream.
For example, a vehicle manufacturer produces a car (the good). Under LCA reporting for the good (e.g. for a Product Carbon Footprint or PCF), upstream emissions are those arising from its production and inputs (including fuels) regardless of whether they occur in the manufacturer’s factories or from the operations of its suppliers. Use phase emissions for the car come from burning fuel in it and from its maintenance. Downstream emissions arise from the car’s disposal.
For the same car, under corporate reporting, the company’s emissions from fuel use and electricity go into scopes 1 and 2. In scope 3, upstream emissions come from the suppliers who provide the raw materials and components to make the car e.g. steel, rubber and textiles. The suppliers might provide PCFs for the goods they supply to help calculate these emissions. Scope 3 downstream emissions come primarily from the customers who use the car and also from its repair, maintenance and disposal.
For more in-depth understanding of LCA in general, you may find [this article (opens in a new tab)](https://en.wikipedia.org/wiki/Life-cycle_assessment)
and [this website (opens in a new tab)](https://consequential-lca.org/)
helpful.
Using LCA activities with Climatiq[](#using-lca-activities-with-climatiq)
--------------------------------------------------------------------------
Emission factors in Climatiq’s database represent activities involved in the production of a good or service. Each emission factor or group of emission factors has a name and `activity_id`. Where Climatiq has data for more than one lifecycle activity for a good or service then there will be multiple emission factors with the same name and `activity_id` but different `source_lca_activity` labels.
For example, many emission factors with the name “Electricity supplied from grid” and activity\_id `electricity-supply_grid-source_supplier_mix` have two `source_lca_activity` labels: `electricity_generation` and `well_to_tank`.
Our [LCA activity tutorial](/docs/guides/tutorials/lca)
explains what these `source_lca_activity` entries mean and how to use them.
[ISO 14083 reporting with Freight](/docs/guides/understanding/freightv2-ISO14083 "ISO 14083 reporting with Freight")
[How To Report Biogenic CO2](/docs/guides/understanding/biogenic_co2 "How To Report Biogenic CO2")
---
# Biogenic CO2 and accounting concepts - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How To Report Biogenic CO2
Biogenic CO2 and accounting concepts
====================================
Biogenic carbon dioxide (CO2) emissions come from the combustion or decomposition of biomass - plant or animal material. The most relevant source of biogenic CO2 for many organizations is the combustion of biofuels such as biodiesel and ethanol.
The Greenhouse Gas Protocol (GHGP) and reporting regulations and standards including the Corporate Sustainability Reporting Directive (CSRD) / European Sustainability Reporting Standards (ESRS), require organizations to disclose biogenic emissions separately (often called ”outside of scopes”). However, as with many disclosures, this is only needed if the disclosure is [relevant to (would affect the decision of) stakeholders (opens in a new tab)](https://www.efrag.org/sites/default/files/sites/webpublishing/SiteAssets/ESRS%201%20Delegated-act-2023-5303-annex-1_en.pdf)
.
Biogenic emissions are only likely to be relevant if the company burns a lot of biofuels or agriculture / land-use change forms a large part of its supply chain. Even if biogenic emissions are not relevant for mandatory corporate reporting they may still be relevant for internal reporting purposes or for reporting against the Global Reporting Index (GRI).
Climatiq has a simple way for organizations that use biofuels to meet external and internal reporting needs.
The first part of this guide explains what biogenic CO2 emissions are and the accounting concepts. The second part explains how to use Climatiq endpoints to report biogenic CO2 and other emissions from biofuels.
What are biogenic CO2 emissions?[](#what-are-biogenic-co2-emissions)
---------------------------------------------------------------------
When plants (biomass) grow they remove carbon dioxide (CO2) from the air through photosynthesis and store it as carbon. When they are burned (combusted) this carbon is released as carbon dioxide and a small amount of methane (CH4).
Why are biogenic CO2 emissions reported separately?[](#why-are-biogenic-co2-emissions-reported-separately)
-----------------------------------------------------------------------------------------------------------
Carbon dioxide emissions from burning biomass add to the stock of carbon dioxide in the atmosphere that traps heat and causes climate change. Unlike fossil fuels, however, the carbon dioxide added to the atmosphere was typically removed from the atmosphere within the past few years and so the net addition to the atmosphere is taken to be zero.
Rather than include both the removal and emissions in scope 1 the accounting has been simplified by requiring that neither are included.
This leaves a gap in reporting, though; if a company reports reduced scope 1 emissions then this could be because they use less energy or a cleaner fossil fuel or biofuels. It could even be that they have increased energy use but balanced that by using biofuels. Biogenic emissions are needed to complete the picture.
From a more strategic point of view, biogenic emissions are also needed to understand the company’s dependence on biomass as an energy source. This should then prompt stakeholders to ask questions about the biofuels such as whether they are from sustainable sources.
There is a huge amount of debate over the use and reporting of biogenic emissions and this guide is intended only to provide the information that is needed to report biogenic CO2; for more information see, for example, the [GHG Protocol draft guidance (opens in a new tab)](https://ghgprotocol.org/land-sector-and-removals-guidance)
.
Note that carbon emissions from the degradation of biomass (e.g. due to soil loss or from waste treatment as compost) are even more complex and are outside of the scope of this guide.
What emissions are reported in each scope ?[](#what-emissions-are-reported-in-each-scope-)
-------------------------------------------------------------------------------------------
Scope 1 should include direct emissions of methane (CH4) and nitrous oxide (N2O) from sources owned or operated by the reporting organization including emissions from combustion of fuels. Focusing on fuels, methane emissions come from incomplete combustion of fuels and nitrous oxide emissions come from the combination of nitrogen in the fuels and oxygen in the air during combustion.
These emissions, unlike biogenic CO2, are additions to the stock of greenhouse gases in the atmosphere. They must therefore be reported in scope 1.
The same logic applies to scope 2 - only CH4 and N2O emissions from biofuel combustion in electricity generation are reported in scope 2.
Scope 3 is more complex as it potentially includes emissions (and removals) from agriculture and other land-use and changes in land-use. The GHG Protocol draft guidance addresses this in detail. In brief, and at present, scope 3 reporting typically includes long-term changes in carbon stocks (e.g. from deforestation) but excludes short-term changes (e.g. planting and then burning biofuels).
* * *
Using Climatiq’s data and endpoints to report biogenic emissions
================================================================
How do I report biogenic (outside of scopes) and scope 1 emissions?[](#how-do-i-report-biogenic-outside-of-scopes-and-scope-1-emissions)
-----------------------------------------------------------------------------------------------------------------------------------------
If you have access to the [Energy feature](/docs/api-reference/energy)
then biogenic emissions are included, where applicable, in the API response.
If you want to use the [estimate endpoint](/docs/api-reference/estimate)
then there are two stages to reporting emissions:
1. Find the right emission factor
2. Estimate emissions
### 1\. Find the right emission factor[](#1-find-the-right-emission-factor)
All biofuels and biofuel blends are identified by the text “bio\_” within the fuel **type** in the activity\_id where the activity\_id takes the format fuel\_**type**…fuel\_use:
Examples:
* biodiesel\_bio\_100
* gasoline\_E85\_bio\_85
* motor\_gasoline\_E10\_bio\_10
* motor\_gasoline\_bio\_average
The number or text after bio\_ is the percentage of the fuel that is biofuel. For pure biofuels this number is 100. Most vehicle fuels contain some biofuel. In Europe and North America this is typically 10% for gasoline / petrol and the fuel is referred to as E10 (for 10% ethanol) and the fuel\_type is therefore “motor\_gasoline\_E10\_bio\_10”. As blends sold in petrol / gasoline stations change over time, some sources (e.g. BEIS) use “average” for consistency in naming and this is reflected in the fuel\_type e.g. “motor\_gasoline\_bio\_average”.
Note for existing biogenic emission factor users: you will see that the fuel type has changed (e.g. petrol and gasoline are now called “motor gasoline”) - this is part of a larger project that Climatiq has done to make choosing emission factors simpler - standardization of fuel\_type between sources. See the separate [guide to fuel\_type normalization](/docs/guides/understanding/fuel_activity_id)
.
### 2\. Estimate emissions using the source\_lca\_activity[](#2-estimate-emissions-using-the-source_lca_activity)
All emission factors have one or more [source\_lca\_activity](/docs/guides/tutorials/lca)
that refer to the lifecycle stage that emissions come from. For scope 1 you need to use the source\_lca\_activity **fuel\_combustion** and for biogenic CO2 (outside of scopes) use **biogenic\_CO2\_combustion.** You will need to use the [estimate endpoint](/docs/api-reference/estimate)
to calculate biogenic CO2 emissions. The API calls are identical apart from the source\_lca\_activity:
**Scope 1**
{ "emission_factor": { "activity_id": "fuel-type_biodiesel_bio_100-fuel_use_na", "data_version": "^16", "source_lca_activity": "fuel_combustion" }, "parameters": { "weight": 1000 }}
**Biogenic CO2 / Outside of scopes**
{ "emission_factor": { "activity_id": "fuel-type_biodiesel_bio_100-fuel_use_na", "data_version": "^16", "source_lca_activity": "biogenic_co2_combustion" }, "parameters": { "weight": 1000 }}
You can also report upstream emissions from fuel production under scope 3.3 (Fuel and Energy-Related Activity) using the source\_lca\_activity “well-to-tank” where the source provides the relevant emission factor. For more information on using the estimate endpoint see the [guide here](/docs/api-reference/estimate)
. For more details on LCA activities see the [guide here](/docs/guides/tutorials/lca)
.
### How do I report biogenic CO2 emissions related to scopes 2 and 3?[](#how-do-i-report-biogenic-co2-emissions-related-to-scopes-2-and-3)
Global Reporting Initiative (GRI) requires organizations to report biogenic CO2 emissions from scope 2 (purchased electricity, heat and steam) and scope 3 separately from those scopes. Other reporting standards and regulations (e.g. GHGP, CSRD / ESRS E1) only require these to be reported if they are material / relevant (would affect the decision of a stakeholder). In practice, few sources publish the emission factors required to make these disclosures and few, if any, organizations report these emissions.
**Scope 2**
The UK Government (BEIS) is the only source we are currently aware of that publishes biogenic emissions from electricity generation (scope 2) and this is because biomass forms a significant proportion of the UK’s electricity fuel mix. To report biogenic emissions from electricity generation in the UK use source: “BEIS”, activity\_id: “electricity-supply\_grid-source\_supplier\_mix” and source\_lca\_activity: “biogenic\_CO2\_combustion” using the estimate endpoint as explained for scope 1 above.
**Scope 3**
Many purchased goods, mainly agricultural goods, contain some element of biogenic CO2 emissions - either from combustion of biofuels or from land-use (e.g. soil loss) or land-use change (e.g. deforestation) but these are not always separately identified in the emission factors by the sources Climatiq uses. If you are looking for a way to calculate land-use & land-use change emissions please reach out to us through the [contact form (opens in a new tab)](https://www.climatiq.io/contact-us)
.
[A Quick Guide to Lifecycle Assessments](/docs/guides/understanding/lca-activity "A Quick Guide to Lifecycle Assessments")
[How To Use Fuel activity\_id](/docs/guides/understanding/fuel_activity_id "How To Use Fuel activity_id")
---
# A guide to fuel activity_id - Climatiq How-To Guides - Automated Carbon Emission Calculations
Guides
Understand
How To Use Fuel activity\_id
A guide to fuel activity\_id
============================
Climatiq’s database draws on many different sources for fuel emission factors and each source names their activities in a different way. Climatiq’s Activity ID contains a normalized, standard fuel name, allowing you to easily find emission factors and perform calculations across different years, regions, and sources.
We have also revised some of the emission factor names to give them a more consistent format while keeping them close to the original name given by the source.
What is the Activity ID?[](#what-is-the-activity-id)
-----------------------------------------------------
Climatiq assigns an activity ID (field: `activity_id`) to every emission factor in the database. The same Activity ID can be shared between many emission factors for the same activity; our normalization process groups together emission factors describing the same activity across all regions, years, sources, LCA stages and unit types. See more details [in this guide](/docs/guides/understanding/what-is-an-activity-id)
.
The Activity ID (field: `activity_id`) contains two components for fuels:
* **“type”**: this is the normalized fuel name (e.g. motor gasoline)
* **“fuel\_use”**: some sources provide a general (stationary or mobile) or specific (e.g. aviation) use
The next two sections explain the changes we have made to these two components.
Changes to fuel type[](#changes-to-fuel-type)
----------------------------------------------
Climatiq has undertaken an extensive process of improving the normalization of `activity_id` for fuels, reducing the number of unique “type” by one-third without reducing the number of emission factors.
We have, as far as possible, used the most common fuel name as the normalized fuel\_type and this is usually the IPCC name. The key examples of changes we have made are:
* gasoline, petrol, motor\_gasoline → motor\_gasoline
* avgas, aviation\_gasoline, aviation\_gas → aviation\_gasoline
* lignite\_coal, lignite, coal\_lignite → coal\_lignite
* anthracite, anthracite\_coal, coal\_anthracite → coal\_anthracite
We group together terms that would tend to be used in similar applications, hence we group coal types together under the prefix “coal” to keep these together when sorted alphabetically. For the same reason we have chosen aviation\_gasoline (rather than gasoline\_aviation) to keep it consistent with aviation\_turbine\_fuel.
### Gross and net calorific value labels[](#gross-and-net-calorific-value-labels)
Where activity is measured using energy (unit\_type “energy”) e.g. kWh or GJ, some sources, most notably the UK Government (BEIS, DEFRA), provide two emission factors, one using gross calorific / higher heating values (gross CV) and one using net calorific / lower heating (net CV) values.
Fossil fuels tend to be invoiced on a gross CV basis when they are not invoiced on a volume or weight basis. Natural gas is the most common example of this. The [UK Government’s guidance (opens in a new tab)](https://assets.publishing.service.gov.uk/media/5a7ed183ed915d74e6226a61/pb14075-ghg-common-queries-140401.pdf)
notes:
_"In general, unless you have specific knowledge about your fuels that would lead you to choose “Net CV”, organizations should use “Gross CV” factors by default. If you are unsure on what basis you are billed for energy then ask your energy supplier, or if you know the the quantity (volume or weight) of fuel purchased then use that instead."_
To make it easier to switch between unit\_type (weight, volume, energy), we have removed the \_gross suffix from the “type” for all fuels. The \_net suffix remains where appropriate. For example:
* natural\_gas, natural\_gas\_gross, natural\_gas\_upper\_heating\_value → natural\_gas
* burning\_oil, burning\_oil\_gross → burning\_oil
* burning\_oil\_net → burning\_oil\_net
* natural\_gas\_net → natural\_gas\_net
Biofuels are more usually measured on a net CV basis (for unit\_type “energy”) and so the emission factors are normally provided by the sources on a net CV basis. We are therefore making that explicit in the Activity ID by using the **\_net** suffix where applicable:
* biodiesel → biodiesel\_net
* bioethanol → bioethanol\_bio\_100\_net
**Biofuel-specific changes**
To make it easy to find biofuels and biofuel blends and understand the proportion of biofuels in fuels we label fuels with a biogenic element with a suffix **bio\_x** where **x** is the percentage of the fuel that comes from biomass.
For some sources the biofuel blend is not a specific percentage but represents the average blend for the particular region. In this case we use the suffix **bio\_average**. The main examples of this are vehicle fuels sold by petrol / gas stations, natural gas supplied through the mains and “renewable” or “development” fuels.
Examples:
* biodiesel\_100percent, biodiesel\_biofuel, biodiesel → biodiesel\_bio\_100
* wood\_chips → wood\_chips\_bio\_100
* ethanol\_100percent, ethanol → bioethanol\_bio\_100
* gasoline\_10\_percent\_bioethanol\_blend → gasoline\_E10\_bio\_10
* gasoline\_with\_biofuel → motor\_gasoline\_bio\_average
Any of these may be suffixed with **\__net_** where applicable (see above).
Note that the emission factor name will still remain close to the name given by the source, so that you will still be able to find it.
### Biofuels - biogenic emissions[](#biofuels---biogenic-emissions)
We have made it easier for companies to report biogenic emissions where they may be required by international accounting and reporting standards including the Greenhouse Gas Protocol, CSRD and GRI.
Where biogenic emissions were previously reported under two separate `activity_id` they are now reported under one activity\_id with different LCA Activities. For example:
| **Before** | **Now** |
| --- | --- |
| **Scope 1** | **Scope 1** |
| activity\_id: `fuel-type_bioethanol-fuel_use_na` | activity\_id: `fuel-type_bioethanol_bio_100-fuel_use_na` |
| source\_lca\_activity: `fuel_combustion` | source\_lca\_activity: `fuel_combustion` |
| | |
| **Outside of scopes (biogenic)** | **Outside of scopes (biogenic)** |
| activity\_id: `fuel-type_bioethanol_biogenic_CO2-fuel_use_na` | activity\_id: `fuel-type_bioethanol_bio_100-fuel_use_na` |
| source\_lca\_activity: `fuel_combustion` | source\_lca\_activity: `combustion_biogenic_co2` |
To obtain the scope 1 emissions from fuel combustion you can continue to use the LCA\_activity **fuel\_combustion**. To obtain the biogenic emissions you will need to use the new LCA\_activity **biogenic\_co2\_combustion**.
See our detailed guide on calculating and reporting biogenic emissions [here](/docs/guides/understanding/biogenic_co2)
.
Changes to fuel use[](#changes-to-fuel-use)
--------------------------------------------
Greenhouse gas emissions from the same fuel can vary a small amount depending on what equipment (e.g. car, truck, lawnmower, generator) is being used. The emission factors for CO2 are not affected, just the emissions factors for Methane (CH4) and nitrous oxide (N2O) which vary according to the combustion efficiencies and different types of emissions-limiting filters and devices that are fitted. As CH4 and N2O typically form a tiny proportion of emissions these difference are usually far too small to make a difference in reporting. However, Climatiq hosts a wide range of emission factors for different fuel uses where the sources provide these.
At a high level the split is between stationary and mobile. Some sources then provide additional specific uses. As for fuel names, different sources use different terms for the same fuel use. We have normalized these fuel use terms to make it easier to select the right emission factors.
Key examples of fuel\_use changes are:
* stationary\_combustion → stationary
* mobile, transport → mobile
* transport\_aviation → mobile\_aviation
* electric\_power, electricity\_generation → electricity\_generation
* residential, domestic → domestic
The **fuel\_use** “na” is still used where the source does not specify a particular use and the emission factor could be applied to any use.
In some cases we have changed the type and fuel use; for example see the two complete Activity IDs below:
* **fuel-type**\_compressed\_natural\_gas\_cng\_heavy\_duty\_vehicles-**fuel\_use**\_transport → **fuel-type**\_cng-**fuel\_use**\_mobile\_hdv
* **fuel-type**\_diesel\_oil\_euro\_iv\_or\_higher\_heavy\_duty\_vehicles-**fuel\_use**\_transport → **fuel-type**\_diesel-**fuel\_use**\_mobile\_hdv\_euro\_iv\_higher
Note that although sources may specify a fuel use it does not necessarily make that emission factor invalid for another use. The difference between emissions from the same fuel but different uses is typically insignificant (<1%).
Abbreviations[](#abbreviations)
--------------------------------
Abbreviations are used in the fuel\_type and fuel\_name where these are commonly used in the source fuel names or fuel uses. The abbreviations are:
### Fuels[](#fuels)
LPG - liquefied petroleum gas
LNG - liquefied natural gas
CNG - compressed natural gas
HVO - hydrotreated vegetable oil (a form of biodiesel)
ME / FAME - fatty acid methyl esters (a form of biodiesel)
### Fuel uses / vehicles[](#fuel-uses--vehicles)
LDV - light-duty vehicle
HDV - heavy-duty vehicle
MHDV - medium and heavy-duty vehicles
HDPI - vehicle with High Pressure Direct Injection fuel system
SI - vehicle with Spark Ignition fuel system na - not specified by the source
### Others[](#others)
CV - Calorific value / heating value.
[How To Report Biogenic CO2](/docs/guides/understanding/biogenic_co2 "How To Report Biogenic CO2")
---
# Regions - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Regions
Regions
=======
The geographical location of an emission-generating activity or the location of financial expenditure is important when it comes to carbon emissions estimations.
Different farming and production practices, electricity grid makeups, and other regional factors can make a big difference in how much the same activity emits. Every Climatiq emission factor specifies a region it is valid for.
Climatiq allows you to define the region of an activity in two ways:
* Region Codes: These are text-based identifiers that define the geographic scope.
* Location Objects: These provide more flexible ways to input precise location data.
Region Code[](#region-code)
----------------------------
A region code in Climatiq is a way to represent a geographical area. This identifier shows up in emission factors and can be used as input for various endpoints. Region codes come in two different formats:
### Country-Level Region Code[](#country-level-region-code)
The most common format for region codes is the country-level region code. It is a two-letter country code, like `DK` for Denmark or `GB` for Great Britain. Apart from the special cases (see below), these codes follow the [ISO 3166-1 alpha-2 standard (opens in a new tab)](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
.
The majority of emission factors are applicable at the country level. This means that when you are using a region code for input, the country-level region codes is often detailed enough. Using an extended region code will often not lead to more accurate estimations.
### Extended Region Code[](#extended-region-code)
When you need more precision, Climatiq supports specifying an extended region code, consisting of two parts. The first part is a country-level region code, and the second is an extension. The two parts are separated by a hyphen(-).
Extensions can be:
* [ISO-3166-2 (opens in a new tab)](https://en.wikipedia.org/wiki/ISO_3166-2)
subdivision codes: Representing states, provinces, or similar administrative regions.
* A [UN/LOCODE (opens in a new tab)](https://unece.org/trade/cefact/unlocode-code-list-country-and-territory)
representing locations such as cities, airports, railway stations and similar.
**Examples:**
* `US-CA` for California, United States
* `US-NY` for New York State, United States
* `US-NYC` for New York City, United States
* `GB-LND` for London, United Kingdom
For the most part, you will only see extended region codes when dealing with:
* Large countries where emissions vary significantly from state to state, such as the United States.
* When using the UN/LOCODEs for a [specific location](/docs/api-reference/regions#unlocode-location)
, in travel or freight-related endpoints.
**Special Cases**
Sometimes emissions data applies in ways that are not covered by the above standards. In cases like that you might see region strings that have values in them that do not follow the standards.
Some examples of these region codes are:
* `EU` for emission factors applicable within the European Union
* `GLOBAL` for emission factors that are applicable globally
* `US-AKGD` is the region covering the ASCC Alaska power Grid
* `ROW_WF` is for emission factors that cover "Africa except Egypt and South Africa"
Some of these special cases might have underscore in the names. Underscores do not necessarily mean it is a extended region code, as only hyphens denote that.
Location[](#location)
----------------------
Scenarios that require a higher level of precision, which is often when dealing with shipping or travel, Climatiq supports Location objects. These allow you to specify specific locations in different ways, based on the data you have available.
### Query Location[](#query-location)
A Query Location allows Climatiq to search for a match based on free-text input, such as addresses or city names. It is particularly useful for unstructured data.
| Query Location Attributes | Required |
| --- | --- |
| **query** _string_
A free text description of the location, like `"Berlin, Germany"`, or `"10 Downing Street"`. | _optional_ |
| **country** _string_
The 2-letter [ISO-3166 country code (opens in a new tab)](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
for a given location. | _optional_ |
| **postal\_code** _string_
The postal (or zip) code for the location. If used, `country` or `query` must also be specified. | _optional_ |
At least one of the following is required:
* `query` alone
* `country + postal_code`
Not all countries have support for postal codes, and the format might be different from country to country. See [this table (opens in a new tab)](https://www.here.com/docs/bundle/geocoder-api-developer-guide/page/topics/coverage-geocoder.html)
for details on postal codes.
### IATA Code Location[](#iata-code-location)
An IATA Code Location allow you to search for locations using IATA airport codes.
| IataLocation Attributes | Required |
| --- | --- |
| **iata** _string_
An IATA airport code. | **required** |
### UN/LOCODE Location[](#unlocode-location)
A UN/LOCODE location allows you to use an [extended region code](/docs/api-reference/regions#extended-region-code)
to find a location.
| UNLocode Location Attributes | Required |
| --- | --- |
| **locode** _string_
An [extended region code](/docs/api-reference/regions#extended-region-code)
like `DE-BER` for Berlin. It must be an extended region code with the second part being a UN/LOCODE. | **required** |
### Coordinate Location[](#coordinate-location)
A Coordinate Location lets you use latitude and longitude to define a location, and you can optionally include a country code.
| Coordinate Location Attributes | Required |
| --- | --- |
| **longitude** _float_
The longitude of the coordinate. | **required** |
| **latitude** _float_
The latitude of the coordinate. | **required** |
| **country** _string_
Climatiq automatically determines the country the coordinates are within. If the automatically determined country is wrong, you can override this selection by supplying a 2-letter country code. | **optional** |
[Data Versioning](/docs/api-reference/data-version "Data Versioning")
[Batch Endpoints](/docs/api-reference/batch-endpoints "Batch Endpoints")
---
# Batch Endpoints - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Batch Endpoints
Batch Endpoints
===============
Many of the endpoints in the Climatiq API have batch variants for handling multiple operations in a single request. These endpoints are particularly useful when you have a substantial amount of data to process and are seeking optimal performance. By using batch endpoints, you not only reduce the overhead associated with multiple HTTP connections but also benefit from the batch-specific optimizations that Climatiq implements.
Endpoints that have a batch variant will have this documented next to the endpoint in the API reference documentation for that endpoint, such as [basic estimate](/docs/api-reference/estimate#batch-estimate-endpoint)
or [procurement](/docs/api-reference/procurement#batch-procurement-endpoint)
.
When working with batch endpoints, you'll find that they uniformly accept arrays, and return an object with a `results` array inside it. Each element in the request array should be a standalone body that would typically be sent to the regular endpoint. Correspondingly, the `results` array contains individual results for each of these elements.
Batch endpoints always preserves the order between requests and responses. This means that the first request object always corresponds to the first response object, the second request object to the second response object and so on.
Currently, all batch endpoints are limited to a maximum of 100 operations per request. If you supply more than 100 elements, an error is returned.
Handling Errors[](#handling-errors)
------------------------------------
Individual operations within batch endpoints can fail for a variety of reasons. However, the batch endpoints returns a status code of `200`, even if some or all of the operations within it fail. To determine what operations have failed, you should inspect the result of each operation. For more details on errors in the Climatiq API, see the [errors documentation](/docs/api-reference/errors)
While for the most part operations fail independently, the entire batch endpoint call might fall. This can happen e.g. if the JSON body is not parseable, or your authorization is invalid.
Example[](#example)
--------------------
An example is the batch variant of the [basic estimate endpoint](/docs/api-reference/estimate#batch-estimate-endpoint)
. Where the regular estimate endpoint might take in the following body:
{ "emission_factor": { "activity_id": "electricity-supply_grid-source_residual_mix", "data_version": "^6" }, "parameters": { "energy": 100, "energy_unit": "kWh" }}
The batch endpoint takes in an array of objects, each which should be a valid body to the non-batch variant. In the example below, we'll call the batch variant with one array element that will lead to a successful operation, and one which won't.
[ { "emission_factor": { "activity_id": "electricity-supply_grid-source_residual_mix", "data_version": "^6" }, "parameters": { "energy": 100, "energy_unit": "kWh" } }, { "emission_factor": { "activity_id": "electricity-supply_grid-source_residual_mix" }, "parameters": { "energy": 100, "energy_unit": "kWh" } }]
And the response body would be as follows, where you can see the second operation has failed because no `data_version` was provided:
{ "results": [ { "co2e": 95.42, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid - residual mix", "activity_id": "electricity-supply_grid-source_residual_mix", "id": "eefd06c3-1c7a-447c-aaf5-fe958bfa470e", "access_type": "public", "source": "AIB", "source_dataset": "European Residual Mix", "year": 2022, "region": "RS", "category": "Electricity", "source_lca_activity": "electricity_generation", "data_quality_flags": ["partial_factor", "notable_methodological_variance"] }, "constituent_gases": { "co2e_total": 95.42, "co2e_other": null, "co2": 95.42, "ch4": null, "n2o": null }, "activity_data": { "activity_value": 100.0, "activity_unit": "kWh" }, "audit_trail": "selector" }, { "error": "bad_request", "error_code": "invalid_input", "message": "Selector should either provide an 'id', OR a 'data_version' and an 'activity_id'. It must not provide both. The latest 'data_version' is '6.6'" } ]}
[Regions](/docs/api-reference/regions "Regions")
[Errors](/docs/api-reference/errors "Errors")
---
# Errors - Climatiq API Reference - Automated Carbon Emission Calculations
API Reference
Errors
Errors
======
While using the Climatiq API, you might encounter errors due to various reasons. In such cases, the API returns an appropriate HTTP status code along with a JSON object containing detailed error information.
You should always check the returned HTTP status code to determine if an error has occurred. If an error is present, examine the provided error object for more details.
Status Codes[](#status-codes)
------------------------------
This is a list of the common HTTP status codes the Climatiq API returns.
* **`200` OK**: Everything worked as expected.
* **`400` Bad Request**: The request was unacceptable, probably due to missing a required parameter.
* **`401` Unauthorized**: No valid API key was provided.
* **`403` Forbidden**: An API key was provided, but it was not valid for the operation you tried to attempt.
* **`404` Not Found**: The requested resource doesn't exist.
* **`429` Too Many Requests**: You have performed too many requests recently.
* **`500` Internal Server Error**: Something went wrong on our end. Please try again a bit later.
* **`503` Service Unavailable**: We're temporarily having trouble providing this service. Please inspect the [Retry-After Header (opens in a new tab)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)
for an appropriate time to retry this request.
Error JSON Structure[](#error-json-structure)
----------------------------------------------
If an error occurs, the API returns a JSON object with the following fields:
| Attribute |
| --- |
| **error** _string_
A string representing the HTTP status code returned. |
| **error\_code** _string_ or _null_
A string providing a more specific error code for certain types of errors. This is primarily provided in cases where we deem it likely that you are able to handle the error programmatically. |
| **message** _string_
A human-readable description of the error. |
The error response might also include additional fields to help you understand the error better, such as valid choices for specific parameters.
{ "error": "bad_request", "error_code": "invalid_unit_type_supplied", "message": "Unable to find any emission factors compatible with the Unit Type provided. This error will contain a list of valid units for this selection.", "valid_values": { "unit_type": ["Number"] }}
Error Codes[](#error-codes)
----------------------------
The API returns error codes for situations where you might want to act programmatically on the returned errors, such as prompting an end-user to provide different input, or rate-limiting your API calls. These error codes depend on the HTTP status code returned. The error codes listed here are not exhaustive and more may be added over time.
### 400 Error Codes (Bad Request)[](#400-error-codes-bad-request)
These error codes are returned when the HTTP status code is 400, indicating that your request is invalid for some reason. You will need to modify the request before trying again.
| Error Code | Description |
| --- | --- |
| `invalid_unit_type_supplied` | The provided unit type did not match any units of found emission factors. Provide a different unit or select a different emission factor. |
| `invalid_input` | The user input does not allow the API call to be completed. This is a generic error code for when more specific ones are not appropriate. |
| `batch_limit_exceeded` | For a batch endpoint, you attempted to batch too many operations at once. Reduce the number of batch operations in one request. |
| `no_route_found` | We could not find a route between two of the provided locations. |
| `no_emission_factors_found` | A query resulted in no valid emission factors being found. Modify your selector. |
| `no_location_found` | We were unable to find a given location or country with the provided information, or the location was not of the expected type. |
| `no_matching_resource_found` | The resource you tried to access, use, or modify did not exist, or you might not have permission to access it. |
| `functionality_unsupported` | The given functionality is currently not supported. If you encounter this error and need the functionality, please reach out to us. |
### 429 Error Codes (Too Many Requests)[](#429-error-codes-too-many-requests)
These error codes are returned when the HTTP status code is 429, indicating that you have performed too many requests. You will need to wait before sending another request.
| Error Code | Description |
| --- | --- |
| `quota_exceeded` | The quota for your project has been exceeded. Please try again next month or upgrade your plan. |
| `temporarily_rate_limited` | You have made too many requests and are temporarily rate-limited. Please try again in a few minutes. Currently Climatiq does not perform rate-limiting of your calls, but we might do so in the future. |
Batch Endpoint Errors[](#batch-endpoint-errors)
------------------------------------------------
Normally, the error codes listed above correspond to HTTP status codes. However, this is not the case for batch endpoints where some operations in the batch might fail independently of each other. This means you might receive an error code that indicates a "Bad Request" for one part of your batch operation, even though the overall request returns a `200` status code.
When handling batch endpoint errors, it is essential to inspect the error information for each individual operation in the batch and take appropriate action accordingly.
[Batch Endpoints](/docs/api-reference/batch-endpoints "Batch Endpoints")
[Search](/docs/api-reference/search "Search")
---