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.

Attribute
cloud_providers An object where each key is the id for a cloud provider, and the corresponding value contains additional data about that cloud provider.

For each cloud provider an object is provided that consists of the following data.

Attribute
provider_full_name string
The full, human-readable name for the provider
provider_id string
The id of the cloud provider. This is the value you must use when specifying provider in the computing endpoints.
regions array of strings
The different available regions for this provider.
virtual_machine_instances array of strings
The different instances you can use in 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

    The unit the duration value is in. The values accepted here are the same as in the Time unit.

    Default Value
    h
  • yearinteger

    The year that the computing resources were used. Climatiq will pick emission factors that is as close to the supplied year as possible.

    Default Value
    Latest year available
  • average_vcpu_utilizationfloat

    How much the vCPU's on the instance are utilized in the given timeframe you are estimating for. Must be a number between 0 and 1

    Default Value
    0.5
  • overridesoverrides object

    If you need more fine-grained control over some behaviour, you may specify an object with overrides to further customize the endpoint behaviour.

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.

Attribute
cpu_estimate Estimation
An estimate corresponding to the electricity used for the CPU part of the instance.
memory_estimate Estimation
An estimate corresponding to the electricity used for the memory (RAM) part of the instance.
embodied_cpu_estimate Estimation
An estimate corresponding to the embodied emissions, meaning the emissions related to the manufacturing and disposal of the physical components, of the CPU part of this instance. This is expressed per CPU hour over the expected lifetime of the hardware.
calculation_details object
Metadata about the calculation to better understand the results
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.


The calculation_details object contains the following attributes to help you understand the calculation better.

Attribute
instance string
The string identifying the instance type selected
instance_memory number
The memory in memory_unit that the given instance has. This is what's used as the basis for memory_estimate.
memory_unit string
The unit that the instance_memory is expressed in. Is currently always GB(Gigabytes)
vcpu_cores number
The amount of virtual CPU cores the instance has.
average_vcpu_utilization number
The average utilization over all virtual CPU cores of the instance.
power_usage_effectiveness number
The power usage effectiveness used in the calculations.
energy_used_cpu number
The total amount of energy, expressed in energy_unit used by the CPU part of the instance.
energy_used_memory number
The total amount of energy, expressed in energy_unit used by the memory part of the instance.
energy_unit string
The unit that energy usage is expressed in. Is currently always kWh (kilowatt-hours)
{
    "total_co2e": 0.7437,
    "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": "dfdeec5e-3137-4912-aa2b-1008575cf245",
            "access_type": "public",
            "source": "BEIS",
            "source_dataset": "Greenhouse gas reporting: conversion factors 2023",
            "year": 2023,
            "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.00002136,
            "n2o": 0.000003071
        },
        "activity_data": {
            "activity_value": 0.6675,
            "activity_unit": "kWh"
        },
        "audit_trail": "enabled"
    },
    "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": "dfdeec5e-3137-4912-aa2b-1008575cf245",
            "access_type": "public",
            "source": "BEIS",
            "source_dataset": "Greenhouse gas reporting: conversion factors 2023",
            "year": 2023,
            "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.00001646,
            "n2o": 0.000002366
        },
        "activity_data": {
            "activity_value": 0.5143,
            "activity_unit": "kWh"
        },
        "audit_trail": "enabled"
    },
    "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"
    },
    "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

    The average load across all of your vCPU's specified as a float between 0 and 1. If you have two vCPU's that are both working at 100% efficiency across the calculation duration, you would put in 1. If you have four vCPU's where two are working at 100%, and two are working at 50%, you would put in 0.75 here.

    Default Value
    0.5
  • durationrequired float

    How long the vCPUs are running for.

  • duration_unitstring

    The unit the duration value is in. The values accepted here are the same as in the Time unit.

    Default Value
    h
  • yearinteger

    The year that the computing resources were used. Climatiq will pick emission factors that is as close to the supplied year as possible.

    Default Value
    Latest year available
  • overridesoverrides object

    If you need more fine-grained control over some behaviour, you may specify an object with overrides to further customize the endpoint behaviour.

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 Estimation back with the co2e for the power consumption for the allocated memory for the given duration.

{
    "co2e": 0.0007367,
    "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": "dfdeec5e-3137-4912-aa2b-1008575cf245",
        "access_type": "public",
        "source": "BEIS",
        "source_dataset": "Greenhouse gas reporting: conversion factors 2023",
        "year": 2023,
        "region": "GB",
        "category": "Electricity",
        "source_lca_activity": "electricity_generation",
        "data_quality_flags": []
    },
    "constituent_gases": {
        "co2e_total": 0.0007367,
        "co2e_other": null,
        "co2": 0.0007292,
        "ch4": 1.138e-7,
        "n2o": 1.637e-8
    },
    "activity_data": {
        "activity_value": 0.003558,
        "activity_unit": "kWh"
    },
    "audit_trail": "enabled"
}

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

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

    Default Value
    MB
  • durationrequired float

    How long the data is stored for.

  • duration_unitstring

    The unit the duration value is in. The values accepted here are the same as in the Time unit.

    Default Value
    h
  • yearinteger

    The year that the computing resources were used. Climatiq will pick emission factors that is as close to the supplied year as possible.

    Default Value
    Latest year available
  • overridesoverrides object

    If you need more fine-grained control over some behaviour, you may specify an object with overrides to further customize the endpoint behaviour.

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 Estimation 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"
}

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

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

    Default Value
    MB
  • durationrequired float

    How long the memory is available.

  • duration_unitstring

    The unit the duration value is in. The values accepted here are the same as in the Time unit.

    Default Value
    h
  • yearinteger

    The year that the computing resources were used. Climatiq will pick emission factors that is as close to the supplied year as possible.

    Default Value
    Latest year available
  • overridesoverrides object

    If you need more fine-grained control over some behaviour, you may specify an object with overrides to further customize the endpoint behaviour.

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 Estimation 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"
}

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.

Overrides

The overrides object in the cloud computing endpoints may have the following attributes.

Override attributesRequiredDefault
power_usage_effectiveness number
The power usage effectiveness (opens in a new tab)(PUE) of the data center running your machines. By default, Climatiq uses cloud specific PUE's.		optional
electricity_emission_factor Selector
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.		optional
Basic EstimateCustom Mappings