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

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.

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.

      cloud_providers[x].provider_full_namestring

      The full, human-readable name for the provider

      cloud_providers[x].provider_idstring

      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 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:

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 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 unit.

    • 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.

    • 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

    • 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.

      overrides[x].Power usage effectivenessnumber 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 factorSelector 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

The response includes a list of estimates for the different components of using an instance.

Response parameters
    • 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].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

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:

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.

    • 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 unit.

    • 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.

    • 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.

      overrides[x].Power usage effectivenessnumber 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 factorSelector 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

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:

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 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_unitstring
      Default value: MB

      The unit the data value is in. The values accepted here are the same as in the Data unit.

    • 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 unit.

    • 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.

    • 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.

      overrides[x].Power usage effectivenessnumber 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 factorSelector 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

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:

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 unit.

    • 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 unit.

    • 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.

    • 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.

      overrides[x].Power usage effectivenessnumber 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 factorSelector 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

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.

Basic EstimateCustom Mappings