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
For examples of how to perform calculations for specific services, or extra information about our methodology, please view the Cloud Computing Guide
Metadata
GET Returns metadata, such as what sort of providers and regions are available for the different computing endpoints.
Request
https://api.climatiq.io/compute/v1/metadata
Response
The endpoint will return metadata for all cloud computing endpoints.
- 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.
cloud_providers[x].provider_full_namestringThe full, human-readable name for the provider
cloud_providers[x].provider_idstringThe id of the cloud provider. This is the value you must use when specifying provider in the computing endpoints.
cloud_providers[x].regionsarray of stringsThe different available regions for this provider.
cloud_providers[x].virtual_machine_instancesarray of stringsThe different instances you can use in the Virtual Machine Instance endpoint 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
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
Request
This endpoint accepts the following parameters:
- 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 to get a list of valid instances for each provider.
- durationrequired float
How long the machine is running for.
- duration_unitstringDefault value:
hour
The unit the
duration
value is in. The values accepted here are the same as in the Time unit.Default Valuehour
- yearintegerDefault 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 ValueLatest year available - average_vcpu_utilizationfloatDefault 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
and1
Default Value0.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.The power usage effectiveness (PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.
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"}'
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
The response includes a list of estimates for the different components of using an instance.
- cpu_estimateEstimationWithSourceTrail
An estimate corresponding to the electricity used for the CPU part of the instance.
- memory_estimateEstimationWithSourceTrail
An estimate corresponding to the electricity used for the memory (RAM) part of the instance.
- embodied_cpu_estimateEstimationWithSourceTrail
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_detailsobject
Metadata about the calculation to better understand the results.
calculation_details[x].instancestringThe string identifying the instance type selected
calculation_details[x].instance_memorynumberThe memory in
memory_unit
that the given instance has. This is what's used as the basis formemory_estimate
.calculation_details[x].memory_unitstringThe unit that the
instance_memory
is expressed in. Is currently alwaysGB
(Gigabytes)calculation_details[x].vcpu_coresnumberThe amount of virtual CPU cores the instance has.
calculation_details[x].average_vcpu_utilizationnumberThe average utilization over all virtual CPU cores of the instance.
calculation_details[x].power_usage_effectivenessnumberThe power usage effectiveness used in the calculations.
calculation_details[x].energy_used_cpunumberThe total amount of energy, expressed in
energy_unit
, used by the CPU part of the instance.calculation_details[x].energy_used_memorynumberThe total amount of energy, expressed in
energy_unit
, used by the memory part of the instance.calculation_details[x].energy_unitstringThe unit that energy usage is expressed in. Is currently always
kWh
(kilowatt-hours)
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
POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/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 for more information about how batch endpoints work and how to handle errors.
CPU
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
Request
This endpoint accepts the following parameters:
- 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_utilizationfloatDefault 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 Value0.5
- durationrequired float
How long the vCPUs are running for.
- duration_unitstringDefault value:
hour
The unit the
duration
value is in. The values accepted here are the same as in the Time unit.Default Valuehour
- yearintegerDefault 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 ValueLatest 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.The power usage effectiveness (PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.
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
You will get an 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
POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/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 for more information about how batch endpoints work and how to handle errors.
Storage
Estimation
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
Request
This endpoint accepts the following parameters:
- 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) andhdd
(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 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 for more information.
- data_unitstringDefault value:
MB
The unit the
data
value is in. The values accepted here are the same as in the Data unit.Default ValueMB
- durationrequired float
How long the data is stored for.
- duration_unitstringDefault value:
hour
The unit the
duration
value is in. The values accepted here are the same as in the Time unit.Default Valuehour
- yearintegerDefault 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 ValueLatest 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.The power usage effectiveness (PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.
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
You will get an 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
POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/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 for more information about how batch endpoints work and how to handle errors.
Memory
Estimation
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
Request
This endpoint accepts the following parameters:
- 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_unitstringDefault value:
MB
The unit the
data
value is in. The values accepted here are the same as in the Data unit.Default ValueMB
- durationrequired float
How long the memory is available.
- duration_unitstringDefault value:
hour
The unit the
duration
value is in. The values accepted here are the same as in the Time unit.Default Valuehour
- yearintegerDefault 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 ValueLatest 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.The power usage effectiveness (PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.
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
You will get an 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
POST For bulk data-processing, this endpoint has a batch endpoint variant allowing for up to 100 calculations with one API call.
The batch endpoint is available at:
https://api.climatiq.io/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 for more information about how batch endpoints work and how to handle errors.