API Reference
Climatiq helps you calculate the environmental footprint created by a broad range of emission-generating activities.
We simplify the process of converting your operational activity data into CO2e (carbon dioxide equivalent) estimates, allowing you to understand your impact on the environment and identify actions to manage and reduce it.
Operational activity data can be generated from any actions that result in greenhouse gas emissions, including vehicle rides, energy consumption, flights, logistical operations, manufacturing, agriculture, heating or cooling of buildings, and countless other daily activities.
Using the Climatiq REST API, you can take data from your software and systems and automatically transform that it into CO2e values, using emission factors from a range of validated sources available in the Open Emission Factor Database (OEFDB).
Make your first CO2e estimate with the Climatiq API
Get help with everything from getting an API key to mapping activities onto emission factors
Find the right emission factors for your project
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.
https://beta3.api.climatiq.ioAn emission factor is a value that estimates the quantity of a gas with a global warming potential (GWP) released into the atmosphere, per some unit related to a particular activity.
For example:
electricity-energy_source_grid_mix: Energy consumed using grid electricity, measured in kWh.flight-domestic: Domestic airplane flight, calculated using distance or airport codes.freight_vehicle-vehicle_type_hgv: Transportation of goods on a heavy goods vehicle, measured using weight in kilograms, tonnes (metric tons) or tons (US short tons) and distance in kilometers or miles.
Authenticate the app using API keys as bearer tokens. Always provide the Authorization header containing your API KEY as bearer token:
Authorization: Bearer <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.
Having trouble? Find out how to get API keys here or follow our quickstart guide here.
The Climatiq API uses conventional HTTP response codes to indicate the success or failure of an API request.
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.
404 Not Found: The requested resource doesn't exist.
5xx Server Errors: Something went wrong on our servers.
To enable compression, define an Accept-Encoding header with the value gzip for gzip compression
or br for brotli compression.
Accept-Encoding: gzipEstimation operations are performed to calculate emissions produced by one or more activities, based on multiplying activity data by the appropriate emission factors.
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://beta3.api.climatiq.io/estimateThe method of calculating emission estimates can differ depending on the unit type that the factor accepts and the applicability of the emission factor as indicated in the ID, name and description fields, with further detail provided by the source.
Every factor is linked to a unit type that is specified in the emission factors list inside the unit_type attribute. See all available emission factors in our Data Explorer.
The following parameters can be defined as JSON-encoded body.
curl --request POST \ --url https://beta3.api.climatiq.io/estimate \ --header 'Authorization: Bearer API_KEY' \ --data '{ "emission_factor": { "activity_id": "heat-and-steam-type_purchased" }, "parameters": { "energy": 100, "energy_unit": "kWh" } }'This endpoint returns an Estimation, which includes the total amount of emissions in kgCO2e and the emission factor used to calculate the emissions.
{ "co2e": 22.655980680727033, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Steam and Heat", "activity_id": "heat-and-steam-type_purchased", "uuid": "da80d5f9-7fb2-4cd7-aa45-781479499845", "id": "heat-and-steam-type_purchased", "access_type": "public", "source": "EPA", "source_dataset": "GHG Emission Factors Hub", "year": "2022", "region": "US", "category": "Heat and Steam", "lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 22.63273546583769, "ch4": 0.0004265177043916345, "n2o": 0.00004265177043916345 }}POST Batch estimations can be used to calculate multiple emission estimations in a single request. Currently limited to maximum 100 operations per request.
https://beta3.api.climatiq.io/batchcurl --request POST \ --url https://beta3.api.climatiq.io/batch \ --header 'Authorization: Bearer API_KEY' \ --data '[ { "emission_factor": { "activity_id": "passenger_vehicle-vehicle_type_car-fuel_source_na-engine_size_na-vehicle_age_na-vehicle_weight_na" }, "parameters":{ "distance": 100, "distance_unit": "km" } }, { "emission_factor": { "activity_id": "consumer_goods-type_snack_foods" }, "parameters": { "money": 15, "money_unit": "usd" } }]'The response includes a list of Estimations.
{ "results": [ { "co2e": 20.756966813807363, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Passenger Car", "activity_id": "passenger_vehicle-vehicle_type_car-fuel_source_na-engine_size_na-vehicle_age_na-vehicle_weight_na", "uuid": "a41de667-978a-4a2a-942e-dc376d66ebcb", "id": "passenger_vehicle-vehicle_type_car-fuel_source_na-engine_size_na-vehicle_age_na-vehicle_weight_na", "access_type": "public", "source": "EPA", "source_dataset": "GHG Emission Factors Hub", "year": "2022", "region": "US", "category": "Vehicles", "lca_activity": "use_phase", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 20.629523582279486, "ch4": 0.00043495983456613376, "n2o": 0.00043495983456613376 } }, { "co2e": 6.119999999999999, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Snack foods", "activity_id": "consumer_goods-type_snack_foods", "uuid": "cc88464e-4d13-42c0-9723-b334ed3025d3", "id": "consumer_goods-type_snack_foods", "access_type": "public", "source": "EPA", "source_dataset": "Supply Chain Factors Dataset (commodities)", "year": "2022", "region": "US", "category": "Food/Beverages/Tobacco", "lca_activity": "cradle_to_shelf", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": null, "co2e_other": 0.13499999999999998, "co2": 5.234999999999999, "ch4": 0.03, "n2o": 0 } } ]}If one or more estimations fail, the result will contain an error code and message for every unsuccessful operation:
{ "results": [ // Successful operation { "co2e": 20.756966813807363, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Passenger Car", "activity_id": "passenger_vehicle-vehicle_type_car-fuel_source_na-engine_size_na-vehicle_age_na-vehicle_weight_na", "uuid": "a41de667-978a-4a2a-942e-dc376d66ebcb", "id": "passenger_vehicle-vehicle_type_car-fuel_source_na-engine_size_na-vehicle_age_na-vehicle_weight_na", "access_type": "public", "source": "EPA", "year": "2022", "region": "US", "category": "Vehicles", "lca_activity": "use_phase", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 20.629523582279486, "ch4": 0.00043495983456613376, "n2o": 0.00043495983456613376 } },
// Failed operation { "error": "not_found", "message": "No emission factors could be found using the current query." } ]}Climatiq allows you to use emission factors from the Global Logistics Emissions Council(GLEC) to calculate the carbon emissions for shipping freight around the world using multiple modes of transport such as by sea, air, road or rail.
POST Calculate total estimated emissions produced by shipping an amount of cargo by the specified route. This endpoint still has a few limitations. More information here.
It is also recommended that you check out the guide, which provides an introduction to using the endpoint and details some of the flexibility it offers.
https://beta3.api.climatiq.io/freight/intermodalThe following parameters can be defined as JSON-encoded object in the body.
curl --request POST \--url https://beta3.api.climatiq.io/freight/intermodal \--header 'Authorization: Bearer API_KEY' \--data '{ "route": [ { "location": { "query": "Hamburg" } }, { "transport_mode": "road", "leg_details": { "vehicle_type": "van", "vehicle_weight": "lte_3.5t" } }, { "location": { "query": "Berlin" } } ], "cargo": { "weight": 10, "weight_unit": "t" }}'A response consists of the following attributes.
{ "co2e": 1951.6340000000002, "co2e_unit": "kg", "distance_km": 287.005, "route": [ { "type": "location", "name": "Hamburg, Germany", "confidence_score": 1 }, { "type": "leg", "co2e": 1951.6340000000002, "co2e_unit": "kg", "transport_mode": "road", "distance_km": 287.005, "estimates": [ { "co2e": 1951.6340000000002, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Van =< 3.5 t", "activity_id": "freight_vehicle-vehicle_type_van-fuel_source_na-vehicle_weight_lte_3.5t-distance_uplift_included", "uuid": "221b2e08-6bf6-4c21-8357-4ca3bfa135ca", "id": "freight_vehicle-vehicle_type_van-fuel_source_na-vehicle_weight_lte_3.5t-distance_uplift_included", "access_type": "public", "source": "GLEC", "source_dataset": "Default Fuel Efficiency and CO2e Intensity Factors", "year": "2019", "region": "EU_S_AMERICA", "category": "Road Freight", "lca_activity": "well_to_wheel", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 1951.6340000000002, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } } ] }, { "type": "location", "name": "Berlin, Germany", "confidence_score": 1 } ], "notices": []}Each route in the request has one or more legs. A leg is a transition between two locations. A leg contains the following properties.
A leg with the "transport_mode": "road", can specify further details about the journey by including this object under leg_details.
Different vehicle_types have different requirements and options. As an example, for some vehicle types, the parameter fuel_source might be optional, and for some it might not be.
A leg with the "transport_mode": "sea", can specify further details about the journey by including this object under leg_details.
A leg with the "transport_mode": "air", can specify further details about the journey by including this object under leg_details.
GLEC default emission factors do not include a Radiative Forcing Index (RFI). 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. If a Radiative Forcing Index has been applied, a Notice will be returned.
A leg with the "transport_mode": "rail"; you can specify further details about the journey by including this object under leg_details.
We have not yet implemented network distance calculations for rail outside of Europe; in the interim we fallback to using the great circle distance between the points.
The GLEC emission factors have a good coverage of Europe, with diesel and electric options and different load types represented. US has more basic factors , while for the rest of the world, in absence of applicable factors, under GLEC guidance we fall back to using a factor reflecting the European average.
Notices should be present in your response if your query has hit any of these limitations.
A trip always has two or more locations.
All the properties are optional, but you must specify at least a query or a country + postal_code. You may specify all three.
Note that not all countries have support for postal codes, and the format might be different from country to country. See this table for details on postal codes.
There are other options that are sometimes relevant to change, particularly if the location is travelled to or from is a fixed-transition point leg
These are more in-depth explanations of the models returned by the intermodal freight endpoint.
The location in the route array of the response will contain the following properties
The leg in the route array of the response will contain the following properties
The notices array can contain objects like these:
In addition to direct calculation of emissions per passenger-kilometer, passenger-mile, tonne-kilometer or ton-mile, Climatiq makes endpoints available for calculating emissions based on departure and arrival airports. The API will automatically select an emission factor, currently based on choosing the highest available CO2e value; a specific ID can be selected to override this.
POST Calculate total estimated emissions produced by passenger flights between the specified airports
https://beta3.api.climatiq.io/travel/flightsThe following parameters can be defined as JSON-encoded object in a body.
Flight legs are the constituent elements of a given flight from one location to another; e.g. a flight from Berlin to New York JFK might require 2 legs of Berlin to Hamburg and Hamburg to New York JFK
# First class trip from Berlin to Hamburg for two passengers.# Followed by a trip from Hamburg to New York JFK for two passengers in economy class.curl --request POST \ --url https://beta3.api.climatiq.io/travel/flights \ --header 'Authorization: Bearer API_KEY' \ --data '{ "legs": [ { "from": "BER", "to": "HAM", "passengers": 2, "class": "first" }, { "from": "HAM", "to": "JFK", "passengers": 2, "class": "economy" } ] }'The response includes the total emissions for the trip in kgCO2e, and the emissions for each leg of the trip.
{ "co2e": 1366.6594004428948, "co2e_unit": "kg", "legs": [ { "co2e": 116.75541111, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Domestic flight - RF effect unknown", "activity_id": "passenger_flight-route_type_domestic-aircraft_type_na-distance_na-class_na-rf_na", "uuid": "c165f89c-7ab9-4473-bfed-ff5ef99bab6f", "id": "passenger_flight-route_type_domestic-aircraft_type_na-distance_na-class_na-rf_na", "access_type": "public", "source": "UBA", "source_dataset": "ProBas", "year": "2020", "region": "DE", "category": "Air Travel", "lca_activity": "upstream-fuel_combustion", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 116.75541111, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } }, { "co2e": 1249.9039893328948, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Air Travel - Long haul (>= 2300 miles) - RF effect unknown", "activity_id": "passenger_flight-route_type_na-aircraft_type_na-distance_gt_2300mi-class_na-rf_na", "uuid": "468e56b4-fe65-4a2f-9739-103f2fe58239", "id": "passenger_flight-route_type_na-aircraft_type_na-distance_gt_2300mi-class_na-rf_na", "access_type": "public", "source": "EPA", "source_dataset": "GHG Emission Factors Hub", "year": "2022", "region": "US", "category": "Air Travel", "lca_activity": "use_phase", "data_quality_flags": [ "notable_methodological_variance" ] }, "constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 1239.2992373314842, "ch4": 0.004561837683428775, "n2o": 0.03953592658971606 } } ]}POST Calculate total estimated emissions produced by freight flights between the specified airports
https://beta3.api.climatiq.io/freight/flightsThe following parameters can be defined as JSON-encoded object in a body.
Flight legs are the constituent elements of a given flight from one location to another; e.g. a flight from Berlin to New York JFK might require 2 legs of Berlin to Hamburg and Hamburg to New York JFK
# Trip from Berlin to Hamburg with 100 tonnes of cargo.# Followed by a trip from Hamburg to New York JFK of 30 tonnes of cargo.curl --request POST \ --url https://beta3.api.climatiq.io/freight/flights \ --header 'Authorization: Bearer API_KEY' \ --data '{ "legs": [ { "from": "BER", "to": "HAM", "weight": 0.5, "weight_unit": "t" }, { "from": "HAM", "to": "JFK", "weight": 0.5, "weight_unit": "t" } ]}'The response includes the total emissions for the trip in kgCO2e, and the emissions for each leg of the trip.
{ "co2e": 2623.9562904584072, "co2e_unit": "kg", "legs": [ { "co2e": 163.073872325, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Domestic air freight - RF effect unknown", "activity_id": "freight_flight-route_type_domestic-distance_na-weight_na-rf_na", "uuid": "f6a15edc-7cef-4f8e-8a6c-d9649e151851", "id": "freight_flight-route_type_domestic-distance_na-weight_na-rf_na", "access_type": "public", "source": "UBA", "source_dataset": "ProBas", "year": "2020", "region": "DE", "category": "Air Freight", "lca_activity": "upstream-fuel_combustion", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 163.073872325, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } }, { "co2e": 2460.882418133407, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Aircraft (freight - RF effect unknown)", "activity_id": "freight_flight-route_type_na-distance_na-weight_na-rf_na", "uuid": "a7862542-dabb-4721-8082-69f6a9517e6b", "id": "freight_flight-route_type_na-distance_na-weight_na-rf_na", "access_type": "public", "source": "EPA", "source_dataset": "GHG Emission Factors Hub", "year": "2022", "region": "US", "category": "Air Freight", "lca_activity": "use_phase", "data_quality_flags": [ "notable_methodological_variance" ] }, "constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 2440.949394898755, "ch4": 0, "n2o": 0.07521895560245949 } } ]}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
For examples of how to perform calculations for specific services, or extra information about our methodology, please view the Cloud Computing Guide
GET Returns metadata, such as what sort of providers and regions are available for the different computing endpoints.
https://beta3.api.climatiq.io/computeThe endpoint will return metadata for all cloud computing endpoints.
For each cloud provider an object is provided that consists of the following data.
{ "cloud_providers": { "aws": { "provider_full_name": "Amazon Web Services", "provider_id": "aws", "cpu_regions": [ "af_south_1", "ap_east_1", "ap_northeast_1" // ... ], "storage_regions": [ "af_south_1", "ap_east_1" // ... ], "memory_regions": [ "af_south_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", "cpu_regions": [ "central_india", "central_us" // ... ] // ... } // More providers here }}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://beta3.api.climatiq.io/compute/:provider/instanceWhere 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
The following parameters can be defined as a JSON-encoded object in a body.
curl --request POST \--url https://beta3.api.climatiq.io/compute/azure/instance \--header 'Authorization: Bearer API_KEY' \--data '{ "region": "uk_west", "instance": "h8", "duration": 24, "duration_unit": "h"}'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.
The response includes a list of estimates for the different components of using an instance.
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.
The calculation_details object contains the following attributes to help you understand the calculation
better.
{ "total_co2e": 0.7274841489050927, "total_co2e_unit": "kg", "memory_estimate": { "co2e": 0.1290858886490927, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "4ef08623-6d14-4671-b185-04c64ca5d5cc", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "BEIS", "source_dataset": "UK Government GHG Conversion Factors for Company Reporting", "year": "2022", "region": "GB", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.1290858886490927, "co2e_other": null, "co2": 0.1276373604746769, "ch4": 0.000021360784138850794, "n2o": 0.0000030686101464467848 } }, "cpu_estimate": { "co2e": 0.09945363225599999, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "4ef08623-6d14-4671-b185-04c64ca5d5cc", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "BEIS", "source_dataset": "UK Government GHG Conversion Factors for Company Reporting", "year": "2022", "region": "GB", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.09945363225599999, "co2e_other": null, "co2": 0.09833762035199999, "ch4": 0.000016457318399999998, "n2o": 0.0000023641966464 } }, "embodied_cpu_estimate": { "co2e": 0.498944628, "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", "uuid": "1e5983ef-a134-417a-944a-3f1c93b9f61e", "id": "cpu-provider_azure-type_h_series_h8_haswell", "access_type": "public", "source": "CCF", "source_dataset": "Derived from CCF models", "year": "2021", "region": "GLOBAL", "category": "Cloud Computing - CPU", "lca_activity": "upstream-end_of_life", "data_quality_flags": [ "notable_methodological_variance" ] }, "constituent_gases": { "co2e_total": 0.498944628, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } }, "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" }}POST Calculate total estimated use-phase emissions based on the electricity usage for a set number of virtual CPU's (vCPUs)
https://beta3.api.climatiq.io/compute/:provider/cpuWhere 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
The following parameters can be defined as a JSON-encoded object in a body.
curl --request POST \--url https://beta3.api.climatiq.io/compute/azure/cpu \--header 'Authorization: Bearer API_KEY' \--data '{ "cpu_count": 1, "region": "uk_west", "average_vcpu_utilization": 0.75, "duration": 1, "duration_unit": "h"}'You will get an Estimation back with the co2e for the power consumption for the allocated memory for the given duration.
{ "co2e": 0.000687988026, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "4ef08623-6d14-4671-b185-04c64ca5d5cc", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "BEIS", "source_dataset": "UK Government GHG Conversion Factors for Company Reporting", "year": "2022", "region": "GB", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.000687988026, "co2e_other": null, "co2": 0.0006802678169999999, "ch4": 1.1384639999999998e-7, "n2o": 1.63547469e-8 }}POST
Batch Estimations for CPU, allowing you to calculate multiple emission estimations in a single request. Currently limited to maximum 100 operations per request.
https://beta3.api.climatiq.io/compute/:provider/cpu/batchcurl --request POST \--url https://beta3.api.climatiq.io/compute/azure/cpu/batch \--header 'Authorization: Bearer API_KEY' \--data '[{ "cpu_count": 2, "region": "uk_west", "duration": 1, "duration_unit": "h" }, { "cpu_count": 1, "region": "germany", "duration": 1, "duration_unit": "h"}]'The response includes a list of responses, like the regular batch endpoint.
{ "results": [ { "co2e": 0.0010359753359999997, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "4ef08623-6d14-4671-b185-04c64ca5d5cc", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "BEIS", "source_dataset": "UK Government GHG Conversion Factors for Company Reporting", "year": "2022", "region": "GB", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 0.0010359753359999997, "co2e_other": null, "co2": 0.0010243502119999996, "ch4": 1.7143039999999994e-7, "n2o": 2.4627048399999995e-8 } }, { "co2e": 0.0006437211519999998, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid - total supplier mix", "activity_id": "electricity-energy_source_total_supplier_mix", "uuid": "f957d9de-6877-4f1a-b25b-bac9f9d119e6", "id": "electricity-energy_source_total_supplier_mix", "access_type": "public", "source": "AIB", "source_dataset": "European Residual Mix", "year": "2022", "region": "DE", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [ "partial_factor" ] }, "constituent_gases": { "co2e_total": 0.0006437211519999998, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } } ]}POST Calculate total estimated use-phase emissions based on the electricity consumption of storing data for a set amount of time.
https://beta3.api.climatiq.io/compute/:provider/storageWhere 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
The following parameters can be defined as a JSON-encoded object in a body.
curl --request POST \--url https://beta3.api.climatiq.io/compute/aws/storage \--header 'Authorization: Bearer API_KEY' \--data '{ "region": "af_south_1", "storage_type": "ssd", "data": 50, "data_unit": "GB", "duration": 1, "duration_unit": "day"}'You will get an Estimation back with the CO2e for the storage of the data for the given duration.
{ "co2e": 0.0014162076000000003, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "975babce-f89d-45f8-85d6-9bd9a9c303e2", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "CT", "source_dataset": "Climate Transparency Report", "year": "2022", "region": "ZA", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [ "partial_factor" ] }, "constituent_gases": { "co2e_total": 0.0014162076000000003, "co2e_other": null, "co2": 0.0014162076000000003, "ch4": null, "n2o": null }}POST
Batch Estimations for Storage, allowing you to calculate multiple emission estimations in a single request. Currently limited to maximum 100 operations per request.
https://beta3.api.climatiq.io/compute/:provider/storage/batchcurl --request POST \--url https://beta3.api.climatiq.io/compute/aws/storage/batch \--header 'Authorization: Bearer API_KEY' \--data '[{ "region": "af_south_1", "storage_type": "ssd", "data": 50, "data_unit": "GB", "duration": 1, "duration_unit": "day" }, { "region": "ap_east_1", "storage_type": "ssd", "data": 150, "data_unit": "GB", "duration": 1, "duration_unit": "day" }]'The response includes a list of responses, like the regular batch endpoint.
{ "results": [ { "co2e": 0.0014162076000000003, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "975babce-f89d-45f8-85d6-9bd9a9c303e2", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "CT", "source_dataset": "Climate Transparency Report", "year": "2022", "region": "ZA", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [ "partial_factor" ] }, "constituent_gases": { "co2e_total": 0.0014162076000000003, "co2e_other": null, "co2": 0.0014162076000000003, "ch4": null, "n2o": null } }, { "co2e": 0.0034812719999999992, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "b8680f91-f23d-4de1-ad41-458c71a8252d", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "HKEI", "source_dataset": "HK Electric Investments Sustainability Report", "year": "2022", "region": "HK", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [ "notable_methodological_variance" ] }, "constituent_gases": { "co2e_total": 0.0034812719999999992, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } } ]}POST Calculate total estimated use-phase emissions based on the electricity consumption of having memory (RAM) available for a set amount of time.
https://beta3.api.climatiq.io/compute/:provider/memoryWhere 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
The following parameters can be defined as a JSON-encoded object in a body.
curl --request POST \--url https://beta3.api.climatiq.io/compute/gcp/memory \--header 'Authorization: Bearer API_KEY' \--data '{ "region": "us_west_2", "data": 8, "data_unit": "GB", "duration": 24, "duration_unit": "h"}'You will get an Estimation back with the co2e emitted by having the allocated memory available for the given duration.
{ "co2e": 0.0209459712, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "3fea43a8-a66a-4d4e-b112-52b98891a960", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "Google", "source_dataset": "Carbon data across GCP regions", "year": "2021", "region": "US-LAX", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [ "self_reported" ] }, "constituent_gases": { "co2e_total": 0.0209459712, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }}POST
Batch Estimations for Memory, allowing you to calculate multiple emission estimations in a single request. Currently limited to maximum 100 operations per request.
https://beta3.api.climatiq.io/compute/:provider/memory/batchcurl --request POST \--url https://beta3.api.climatiq.io/compute/gcp/memory/batch \--header 'Authorization: Bearer API_KEY' \--data '[{ "region": "us_west_2", "data": 8, "data_unit": "GB", "duration": 24, "duration_unit": "h" }, { "region": "us_west_1", "data": 16, "data_unit": "GB", "duration": 24, "duration_unit": "h"}]'The response includes a list of responses, like the regular batch endpoint.
{ "results": [ { "co2e": 0.0209459712, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "3fea43a8-a66a-4d4e-b112-52b98891a960", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "Google", "source_dataset": "Carbon data across GCP regions", "year": "2021", "region": "US-LAX", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [ "self_reported" ] }, "constituent_gases": { "co2e_total": 0.0209459712, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } }, { "co2e": 0.0129153024, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "source", "emission_factor": { "name": "Electricity supplied from grid", "activity_id": "electricity-energy_source_grid_mix", "uuid": "7f6dff98-e49c-4c8d-a2fa-1392ad172927", "id": "electricity-energy_source_grid_mix", "access_type": "public", "source": "Google", "source_dataset": "Carbon data across GCP regions", "year": "2021", "region": "US-OR", "category": "Electricity", "lca_activity": "electricity_generation", "data_quality_flags": [ "self_reported" ] }, "constituent_gases": { "co2e_total": 0.0129153024, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } } ]}The overrides object in the cloud computing endpoints may have the following attributes.
Many sources link emission factors 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):
For a more in-depth view on how Climatiq works with classification schemes, view the classification guide.
POST Calculate total estimated emissions produced for a particular activity, as described by an industry classification scheme such as ISIC or NACE. All requests are performed by sending a POST request to the following endpoint:
https://beta3.api.climatiq.io/classifications/estimateThis 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, allowing Climatiq to return emission factors from other classification schemes that represent the same activity if there isn't one found directly; this may happen for example because of different classification taxonomies being used in different geographies or by different data sources.
As with any estimation endpoint, the emission factor must be provided with parameters, such as weight, volume, energy. These are provided through the parameters field. See the estimate endpoint for more details on how parameters and units work.
The following parameters can be defined as JSON-encoded object in a body.
The Classification Selector is very reminiscent of a Selector with a few differences. It is an object consisting of the following parameters:
curl --request POST \ --url https://beta3.api.climatiq.io/classifications/estimate \ --header 'Authorization: Bearer API_KEY' \ --data '{ "classification": { "classification_type": "isic4", "classification_code": "25", "source": "EXIOBASE" }, "parameters": { "money": 25.0, "money_unit": "usd" }}'This endpoint returns an Estimation, which includes the total amount of emissions in kgCO2e and the emission factor used to calculate the emissions.
{ "co2e": 46.61037, "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", "uuid": "79e87731-dc29-470b-a2fa-73e30797bc53", "id": "metal_products-type_fabricated_metal_products_except_machinery_equipment", "access_type": "public", "source": "EXIOBASE", "source_dataset": "EXIOBASE 3", "year": "2021", "region": "IN", "category": "Fabricated Metal Products", "lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 46.61037, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }}Instead of using code to specify emission factors you want to use for your calculations, you can map your own activity identifiers to Climatiq IDs in the Climatiq dashboard,
allowing the Climatiq API to recognize whatever values you use to categorize your activities. In the dashboard simply link a custom activity label to an emission factor id,
and this can then be used in the custom activities 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 to be taken step-by-step through mapping custom activities and performing queries.
POST Calculate total estimated emissions produced for a particular activity in kgCO2e
using a custom activity that you have defined under the Activity Mapping tab inside your Climatiq
Dashboard.
A custom activity label provides the same flexibility as the ID it maps to.
This can happen when multiple emission factors share an emission factor id or because you have mapped the same custom activity 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. If there are multiple emission factors Climatiq will automatically pick the most conservative one.
https://beta3.api.climatiq.io/custom-activities/estimateThe following parameters can be defined as JSON-encoded body.
The Custom Activity Selector is very reminiscent of a Selector with a few differences. It is an object consisting of the following parameters:
# In this example, you have already specified "Hotels and accommodation" as a custom activity in the dashboard# and linked it to an emission factor that use the Money unit.curl --request POST \ --url https://beta3.api.climatiq.io/custom-activities/estimate \ --header 'Authorization: Bearer API_KEY' \ --data '{ "custom_activity": { "label": "Hotels and accommodation", "region": "GB" }, "parameters": { "money": 100, "money_unit": "gbp" }}'You will get an Estimation back with the CO2e for the given custom activity, based on the id that it is mapped to in the Activity Mapping tool in the Climatiq Dashboard.
{ "co2e": 42.5, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Holiday (travel/accommodation)", "activity_id": "accommodation_type_holiday", "uuid": "5c37ee77-488d-4a21-83d7-7c06656eb0ff", "id": "accommodation_type_holiday", "access_type": "public", "source": "BEIS", "year": "2018", "region": "GB", "category": "Accommodation", "lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 42.5, "co2e_other": null, "co2": null, "ch4": null, "n2o": null }}POST Batch estimations for custom activities work like regular Batch Estimates, allowing you to calculate multiple emission estimations in a single request, all based on custom activities mapped in the Climatiq Dashboard. Currently limited to maximum 100 operations per request.
https://beta3.api.climatiq.io/custom-activities/batch# In this example, you have already specified "Hotels and accommodation" and "Soda" as custom activities in the dashboard# and linked them to emission factors that use the Money unit.curl --request POST \ --url https://beta3.api.climatiq.io/custom-activities/batch \ --header 'Authorization: Bearer API_KEY' \ --data '[ { "custom_activity": { "label": "Hotels and accommodation", "region": "GB" }, "parameters": { "money": 100, "money_unit": "gbp" } }, { "custom_activity": { "label": "Soda" }, "parameters": { "money": 100 } }]'The response includes a list of responses, like the regular batch endpoint.
{ "results": [ { "co2e": 42.5, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Holiday (travel/accommodation)", "activity_id": "accommodation_type_holiday", "uuid": "5c37ee77-488d-4a21-83d7-7c06656eb0ff", "id": "accommodation_type_holiday", "access_type": "public", "source": "BEIS", "year": "2018", "region": "GB", "category": "Accommodation", "lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 42.5, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } }, { "co2e": 29.7, "co2e_unit": "kg", "co2e_calculation_method": "ar4", "co2e_calculation_origin": "source", "emission_factor": { "name": "Soft drinks/bottled water and ice", "activity_id": "consumer_goods-type_soft_drinks_bottled_water_ice", "uuid": "85119a9d-087f-4f3a-94d5-702d99379964", "id": "consumer_goods-type_soft_drinks_bottled_water_ice", "access_type": "public", "source": "EPA", "year": "2020", "region": "US", "category": "Food/Beverages/Tobacco", "lca_activity": "cradle_to_shelf", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": 29.7, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } } ]}POST Adds new unmapped labels for custom activity mapping 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, where suggestions will be provided for automatic mapping.
https://beta3.api.climatiq.io/custom-activities/labelsThe following parameters can be defined as JSON-encoded objects in an array in the body. 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.
curl --request POST \ --url https://beta3.api.climatiq.io/custom-activities/labels \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '[ { "label": "hotel room", "source": ["BEIS"] }, { "label": "Electricity generation" }]'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.
[ { "label": "hotel", "activity_id": "accommodation_type_hotel_room", "id": "35354707520" }]The Climatiq API can be queried for emission factors in a number of ways, outlined below.
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,
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://beta3.api.climatiq.io/searchcurl --request GET \ --url 'https://beta3.api.climatiq.io/search?query=light+duty+trucks&year=2021' \ --header 'Authorization: Bearer API_KEY'The response includes a list of emission factors filtered by the request parameters above.
Every emission factor returned in the list is formed by the following properties:
{ "current_page": 1, "last_page": 1, "total_results": 3, "results": [ { "activity_id": "fuel_type_diesel-fuel_use_diesel_light_duty_trucks", "uuid": "a3df6355-8eca-47ee-9299-9a3686611461", "id": "fuel_type_diesel-fuel_use_diesel_light_duty_trucks", "name": "Diesel fuel - diesel light-duty trucks", "category": "Fuel", "sector": "Energy", "source": "GHG Protocol", "source_link": "https://ghgprotocol.org/ghg-emissions-calculation-tool", "source_dataset": "GHG Emissions Calculation Tool", "uncertainty": null, "year": "2021", "region": "US", "region_name": "United States", "description": "Emission intensity of mobile combustion of fuel. Includes fuel consumption by vehicles that are owned or leased by the company. The primary source is EPA Emission Factors for Greenhouse Gas Inventories - March 9 2018 - WRI - GHG Protocol - Emission Factors from Cross-Sector Tools - April 2014.", "unit_type": [ "Volume" ], "unit": "kg/gal (US)", "lca_activity": "fuel_combustion", "data_quality_flags": [], "access_type": "public", "supported_calculation_methods": [ "ar4", "ar5" ], "factor": 10.2168931, "factor_calculation_method": "ar5", "factor_calculation_origin": "source", "constituent_gases": { "co2e_total": 10.2168931, "co2e_other": null, "co2": 10.21, "ch4": 0.0000162, "n2o": 0.0000243 } }, {...}, {...} ], "possible_filters": { "year": [ "2021" ], "source": [ "EPA", "GHG Protocol" ], "source_dataset": [ "GHG Emission Factors Hub", "GHG Emissions Calculation Tool" ], "region": [ { "id": "US", "name": "United States" } ], "category": [ "Fuel", "Vehicles" ], "sector": [ "Energy", "Transport" ], "unit_type": [ "Distance", "Volume" ], "lca_activity": [ "fuel_combustion", "use_phase" ], "access_type": [ "public" ], "data_quality_flags": [] }}GET Not all emission factors have data for all years. This endpoint returns a list of years available for a given query.
https://beta3.api.climatiq.io/emission-factors/yearsThe request parameters are the same as for Emission Query
curl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors/years?source=BEIS' \ --header 'Authorization: Bearer API_KEY'{ "results": [ "2022", "2021", "2020", "2019", "2018", "2017", "2016" ]}GET Climatiq aggregates several different sources for the same emission factors, as different organizations often come to different conclusions about how much an activity emits. This endpoint a list of sources available for a given query.
https://beta3.api.climatiq.io/emission-factors/sourcesThe request parameters are the same as for Emission Query
curl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors/sources?year=2021' \ --header 'Authorization: Bearer API_KEY'{ "results": [ "ADEME", "AIB", "BEIS", "CCF", "CLP Group", "CT", "DISER", "EEA", "Electricity Info", "EMA", "EPA", "EXIOBASE", "GEMIS", "GHG Protocol", "Green-e", "HKEI", "UBA", "UNFCCC" ]}GET Many of the sources Climatiq aggregates have several different datasets they release data under. This endpoint lists the different datasets available for a given query.
https://beta3.api.climatiq.io/emission-factors/source-datasetsThe request parameters are the same as for Emission Query
curl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors/source-datasets?source=BEIS' \ --header 'Authorization: Bearer API_KEY'{ "results": [ "UK full dataset including conversion factors by COICOP code (archived)", "UK full dataset including conversion factors by SIC code", "UK Government GHG Conversion Factors for Company Reporting" ]}GET Not all emission factors have data for all geographic regions. This endpoint returns a list of regions available for a given query.
https://beta3.api.climatiq.io/emission-factors/regionsThe request parameters are the same as for Emission Query
curl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors/regions?source=MfE' \ --header 'Authorization: Bearer API_KEY'Every region contains:
{ "results": [ { "id": "NZ", "name": "New Zealand" }, { "id": "NZ-WLG", "name": "Wellington, WGN, NZ" } ]}GET Returns a list of categories available for a given query.
https://beta3.api.climatiq.io/emission-factors/categoriesThe request parameters are the same as for Emission Query
curl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors/categories?source=BEIS' \ --header 'Authorization: Bearer API_KEY'{ "results": [ "Accommodation", "Agriculture/Hunting/Forestry/Fishing", "Air Freight", "Air Travel", "Building Materials", "Chemical Products", "Clothing and Footwear", "Construction", "Construction Waste", "Domestic Services", "Education", "Electrical Equipment", "Electrical Waste", "Electricity", "Electronics", "Energy Services", "Equipment Repair", "Fabricated Metal Products", "Financial Services", "Fishing/Aquaculture/Hunting", "Food and Beverage Services", "Food and Organic Waste", "Food/Beverages/Tobacco", "Fuel", "Furnishings and Household", "General Retail", "General Waste", "Glass and Glass Products", "Government Activities", "Health Care", "Heat and Steam", "Homeworking", "Housing", "Information and Communication Services", "Insurance Services", "Livestock Farming", "Machinery", "Maintenance and Repair", "Manufacturing", "Metal Waste", "Metals", "Mined Materials", "Mining", "Non-profit Activities", "Operational Activities", "Organic Products", "Organizational Activities", "Paper and Cardboard", "Paper and Cardboard Waste", "Paper Products", "Personal Care and Accessories", "Plastic Waste", "Plastics and Rubber Products", "Professional Services and Activities", "Rail Freight", "Rail Travel", "Real Estate", "Recreation and Culture", "Refrigerants and Fugitive Gases", "Road Freight", "Road Travel", "Sea Freight", "Sea Travel", "Social Care", "Textiles", "Tickets and Passes", "Timber and Forestry Products", "Transport Services and Warehousing", "Vehicle Maintenance and Services", "Vehicles", "Waste Management", "Water Supply", "Water Treatment", "Wholesale Trade" ]}GET Returns a list of sectors available for a given query.
https://beta3.api.climatiq.io/emission-factors/sectorsThe request parameters are the same as for Emission Query
curl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors/sectors?source=BEIS' \ --header 'Authorization: Bearer API_KEY'{ "results": [ "Agriculture/Hunting/Forestry/Fishing", "Buildings and Infrastructure", "Consumer Goods and Services", "Education", "Energy", "Equipment", "Health and Social Care", "Information and Communication", "Insurance and Financial Services", "Materials and Manufacturing", "Organizational Activities", "Refrigerants and Fugitive Gases", "Restaurants and Accommodation", "Transport", "Waste", "Water" ]}GET Returns a list of life cycle assessment(LCA) activities available for a given query.
https://beta3.api.climatiq.io/emission-factors/lca-activitiesThe request parameters are the same as for Emission Query
curl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors/lca-activities?source=BEIS' \ --header 'Authorization: Bearer API_KEY'{ "results": [ "cradle_to_shelf", "cradle_to_gate", "electricity_generation", "end_of_life", "fuel_combustion", "gate_to_grave", "transmission_and_distribution", "unknown", "upstream", "use_phase", "well_to_tank" ]}GET Returns a list of unit types available for a given query.
https://beta3.api.climatiq.io/emission-factors/unit-typesThe request parameters are the same as for Emission Query
curl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors/unit-types?source=BEIS' \ --header 'Authorization: Bearer API_KEY'{ "results": [ "Distance", "Energy", "Money", "Number", "PassengerOverDistance", "Volume", "Weight", "WeightOverDistance", "Time" ], "units": [ { "unit_type": "Distance", "units": { "distance_unit": [ "m", "km", "ft", "mi", "nmi" ] } }, { "unit_type": "Energy", "units": { "energy_unit": [ "Wh", "kWh", "MWh", "MJ", "GJ", "TJ", "BTU", "therm", "MMBTU" ] } }, { "unit_type": "Money", "units": { "money_unit": [ "usd", "afn", "dzd", "ars", "aud", "bhd", "brl", "cad", "kyd", "cny", "dkk", "egp", "eur", "hkd", "huf", "isk", "inr", "iqd", "ils", "jpy", "lbp", "mxn", "mad", "nzd", "nok", "qar", "rub", "sar", "sgd", "zar", "krw", "sek", "chf", "twd", "thb", "tnd", "try", "aed", "gbp" ] } }, { "unit_type": "Number", "units": {} }, { "unit_type": "PassengerOverDistance", "units": { "distance_unit": [ "m", "km", "ft", "mi", "nmi" ] } }, { "unit_type": "Time", "units": { "time_unit": [ "ms", "s", "m", "h", "day", "year" ] } }, { "unit_type": "Volume", "units": { "volume_unit": [ "ml", "l", "m3", "standard_cubic_foot", "gallon_us", "bbl" ] } }, { "unit_type": "Weight", "units": { "weight_unit": [ "g", "kg", "t", "ton", "lb" ] } }, { "unit_type": "WeightOverDistance", "units": { "weight_unit": [ "g", "kg", "t", "ton", "lb" ], "distance_unit": [ "m", "km", "ft", "mi", "nmi" ] } } ]}This endpoint has been deprecated because it returns every single emission factor available by default. This leads to a very long response, resulting in several megabytes of traffic transferred. If you must use this endpoint for now, enable compression to significantly reduce the data transfer.
GET Lists all available emission factors or queries with parameters such as category,
source, region, year calculation_method, lca_activity or id to help determine what
emission factors are available to be used in your estimation.
https://beta3.api.climatiq.io/emission-factorscurl --request GET \ --url 'https://beta3.api.climatiq.io/emission-factors?source=BEIS&year=2021' \ --header 'Authorization: Bearer API_KEY'The response includes a list of emission factors filtered by the request parameters above.
Every emission factor returned in the list is formed by the following properties:
{ "results": [ { "id": "fuel_type_avgas-fuel_use_aviation", "name": "Aviation fuel (avgas) WTT", "category": "Fuel", "sector": "Energy", "source": "BEIS", "source_link": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2021", "uncertainty": null, "year": "2021", "region": "GB", "region_name": "United Kingdom", "description": "Emission intensity for aviation fuel (avgas). Well-to-Tank (WTT) fuels conversion factors should be used to account for the upstream Scope 3 emissions associated with extraction and refining and transportation of the raw fuel sources to an organisation’s site (or asset) - prior to combustion. Retrieved from the Conversion Factors 2021: flat file published by the UK BEIS/Defra at the source URL.", "unit_type": [ "Weight" ], "unit": "kg-CO2e/t", "lca_activity": "upstream", "data_quality_flags": [], "supported_calculation_methods": [ "ar4" ], "factor": 815.31014, "factor_calculation_method": "ar4", "factor_calculation_origin": "source", "constituent_gases": { "co2e_total": 815.31014, "co2e_other": null, "co2": null, "ch4": null, "n2o": null } }, {...}, {...} ]}Request models describe the different ways that emission factors can be selected in a query to the Climatiq API.
We collect, normalize, and organize emission factors by a variety of factors such as source, region, and year, allowing for granular selection of the relevant emission factors.
Emission factors can be queried by specifying a set of 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.
A selector for one specific emission factor, using the unique id for that emission factor can look like this:
"emission_factor": { "uuid": "da80d5f9-7fb2-4cd7-aa45-781479499845",}A selector for one a specific activity, with additional filtering criteria can look like this:
"emission_factor": {"activity_id": "freight-goods-truck","source": "MfE","region": "NZ","year": "2020"}Parameters are values passed into the API in order to produce emissions estimations. Click below to find out more about parameters for each unit type.
{ "parameters": { "volume": 10, "volume_unit": "l" //... }}Response models describe the different objects the Climatiq API might return
The estimation response model is returned in a variety of estimation-related endpoints.
The model contains the total amount of emissions in kgCO2e, and includes the emission factor used for the calculation.
{ "co2e": 22.655980680727033, "co2e_unit": "kg", "co2e_calculation_method": "ar5", "co2e_calculation_origin": "climatiq", "emission_factor": { "name": "Steam and Heat", "activity_id": "heat-and-steam-type_purchased", "uuid": "da80d5f9-7fb2-4cd7-aa45-781479499845", "id": "heat-and-steam-type_purchased", "access_type": "public", "source": "EPA", "source_dataset": "GHG Emission Factors Hub", "year": "2022", "region": "US", "category": "Heat and Steam", "lca_activity": "unknown", "data_quality_flags": [] }, "constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 22.63273546583769, "ch4": 0.0004265177043916345, "n2o": 0.00004265177043916345 }}The emission factor model gives you information about which emission factor Climatiq used to serve your query.
"emission_factor": { "name": "Steam and Heat", "activity_id": "heat-and-steam-type_purchased", "uuid": "da80d5f9-7fb2-4cd7-aa45-781479499845", "id": "heat-and-steam-type_purchased", "access_type": "public", "source": "EPA", "source_dataset": "GHG Emission Factors Hub", "year": "2022", "region": "US", "category": "Heat and Steam", "lca_activity": "unknown", "data_quality_flags": []},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
"constituent_gases": { "co2e_total": null, "co2e_other": null, "co2": 22.631796, "ch4": 0.0004265, "n2o": 0.00004265}Unit types describe the categories of units available to be queried by the API for an emission factor. Each emission factor accepts a particular unit type, such as money or volume; any unit described for the unit type is acceptable, as the API will handle conversions.
Calculate emissions produced by an area, such as spraying fields, expressed in hectares (ha), square kilometers (km2), square meters (m2) or square foot (ft2).
{ //... "parameters": { "area": 30, "area_unit": "ha" } //...}Calculate emissions produced by area over time.
{ //... "parameters": { "area": 30, "area_unit": "ha", "time": 365, "time_unit": "day" } //...}Calculate emissions produced by moving goods inside a certain amount of twenty-foot-equivalent containers over a distance (in kilometers, miles, nautical miles, meters or feet).
{ //... "parameters": { "twenty_foot_equivalent": 2, "distance": 100, "distance_unit": "km" } //...}Calculate emissions produced by a data amount, such as by transfer, expressed in megabytes (MB), gigabytes (GB) or Terabytes (TB).
{ //... "parameters": { "data": 3, "data_unit": "GB" } //...}Calculate emissions produced by data over time, such as storing data for some duration.
{ //... "parameters": { "data": 3, "data_unit": "GB", "time": 1, "time_unit": "h" } //...}Calculate emissions produced by moving a vehicle in kilometers, miles, nautical miles, meters or feet.
{ //... "parameters": { "distance": 100, "distance_unit": "mi" } //...}Calculate emissions produced by distance over time, such as road maintenance.
{ //... "parameters": { "distance": 100, "distance_unit": "mi" "time": 365, "time_unit": "days" } //...}Calculate emissions produced by consumption of energy in kWh, terajoules, gigajoules, megajoules or MMBTU.
{ //... "parameters": { "energy": 30, "energy_unit": "TJ" } //...}Calculate upstream emissions produced by purchase of goods or services, for example food, clothing or services, expressed in any of the supported currencies.
Where exchange rates are applied, these are calculated from IRS average exchange rates for the year of publication of the emission factor. Due to varying exchange rates and inflation, calculating emissions based on money spent is most accurate when the year for the emission factor is the same as the year you spent the money.
{ //... "parameters": { "money": 100, "money_unit": "eur" } //...}This method works as a fallback for units without conversions like Hotel nights.
{ //... "parameters": { "number": 3 } //...}Calculate emissions by a number in a given time expressed in days, hours, minutes, seconds or milliseconds. The numbers are multiplied together, so doubling the number or the time will yield the same results.
{ //... "parameters": { "number": 15, "time": 3, "time_unit": "m" } //...}Calculate emissions produced by moving a number of passengers over a given distance in kilometers, miles, nautical miles, meters or feet.
{ //... "parameters": { "passengers": 4, "distance": 100, "distance_unit": "mi" } //...}Calculate emissions in a given time expressed in (average) years, days, hours, minutes, seconds or milliseconds.
{ //... "parameters": { "time": 3, "time_unit": "m" } //...}Calculate emissions produced by volume of material consumed or utilised in a process or activity; for example diesel, expressed in litres, millilitres, cubic metres, standard cubic foot or US gallons.
{ //... "parameters": { "volume": 15, "volume_unit": "l" } //...}Calculate emissions produced by total weight of material consumed, utilised or transported in a process or activity, expressed in kilograms, tonnes (metric tons) or US short tons.
{ //... "parameters": { "weight": 80, "weight_unit": "t" } //...}Calculate emissions produced by moving goods of a certain weight (expressed in kilograms, tonnes (metric tons) or US short tons) over a distance (in kilometers, miles, nautical miles, meters or feet).