Energy Consumption API

This API provides comprehensive data about Filecoin Storage Providers' energy consumption metric.

Good to know: In addition to below there is an Open API documentation available here.

Data Model

The Data Model end point is listing all available data models (e.g. Energy intensity, Energy used to seal data, Energy used to store data, etc.).

List available API data models

GET https://api.filgreen.d.interplanetary.one/models/list

[
    {
        "id": 0,
        "name": "Energy consumption rate (v1.0.1)",
        "code_name": "TotalEnergyModelv_1_0_1",
        "category": "energy",
        "details": "The total rate of electrical energy use. This is the sum of sealing and storage energy use, multiplied by a [Power Usage Effectiveness](https://en.wikipedia.org/wiki/Power_usage_effectiveness) (PUE) representing overhead energy costs such as cooling and power conversion. Bounds and estimate come from combining the bounds and estimates of sealing and storage energy, as well as different values of estimated PUE.\n\n**Network view:** Total electrical power used by the Filecoin network.\n\n**Storage Provider (SP) view:** Electrical power used by this SP.\n"
    },
    {
        "id": 1,
        "name": "Energy used to seal data (v1.0.1)",
        "code_name": "SealingEnergyModelv_1_0_1",
        "category": "energy",
        "details": "[Sealing](https://spec.filecoin.io/systems/filecoin_mining/sector/sealing/) is the process of generating SNARK proofs for a data sector which will allow an SP to prove that they are continuing to store that data over time, and is one of the components of energy use of the Filecoin network. Energy use due to sealing is estimated by multiplying the increase in storage capacity over a given time period by a constant value as described in the methodology. Bounds and estimate come from different values of this constant.\n\n**Network view:** Total electrical power used to seal data for the entire Filecoin network.\n\n**Storage Provider (SP) view:** Electrical power used by this SP to seal data.\n"
    },
    {
        "id": 2,
        "name": "Energy used to store data (v1.0.1)",
        "code_name": "StorageEnergyModelv_1_0_1",
        "category": "energy",
        "details": "The energy used to store data over time, which is a component of the energy used by the Filecoin network. Storage energy use is estimated by multiplying storage capacity by a constant value. Bounds and estimate come from different values of this constant.\n\n**Network view:** Total electrical power used to store all data on the Filecoin network.\n\n**Storage Provider (SP) view:** Electrical power used by this SP to store data.\n"
    },
    {
        "id": 3,
        "name": "Cumulative Energy Use (v1.0.1)",
        "code_name": "CumulativeEnergyModel_v_1_0_1",
        "category": "energy",
        "details": "Total amount of energy used during a time period in kWh"
    },
    {
        "id": 4,
        "name": "Cumulative renewable energy purchases ",
        "code_name": "RenewableEnergyModel",
        "category": "energy",
        "details": "Cumulative renewable energy certificate (REC) purchases over time"
    },
    {
        "id": 5,
        "name": "Energy Intensity",
        "code_name": "EnergyIntensityModel",
        "category": "energy",
        "details": "\n             **Energy Intensity:** Total electrical power used by the Filecoin network \n             divided by data storage Capacity.\n             "
    },
    {
        "id": 6,
        "name": "Data storage capacity added per day",
        "code_name": "SealedModel",
        "category": "capacity",
        "details": "**Network view:** New data storage capacity added to Filecoin’s decentralized storage network (sealed) per day.\n\n**Storage Provider (SP) view:** The amount of new data storage contributed to the network (sealed) by this SP per day.\n"
    },
    {
        "id": 7,
        "name": "Data storage capacity",
        "code_name": "CapacityModel",
        "category": "capacity",
        "details": "**Network view:** The total amount of data storage capacity contributed to Filecoin’s decentralized storage network, based on on-chain proofs.\n\n**Storage Provider (SP) view:** The amount of data storage contributed by this SP, based on on-chain proofs.\n"
    }
]

Available Data Models

Energy Intensity: Total electrical power used by the Filecoin network divided by data storage Capacity. Model: "id": 0 or "code_name": "EnergyIntensityModel"

Renewable Energy Ratio: Model: "id": 1 or "code_name": "RenewableEnergyRatioModel"

Energy consumption rate (v1.0.1): The total rate of electrical energy use. This is the sum of sealing and storage energy use, multiplied by a Power Usage Effectiveness (PUE) representing overhead energy costs such as cooling and power conversion. Bounds and estimate come from combining the bounds and estimates of sealing and storage energy, as well as different values of estimated PUE. Network view: Total electrical power used by the Filecoin network. Storage Provider (SP) view: Electrical power used by this SP. Model: "id": 2 or "code_name": "TotalEnergyModelv_1_0_1"

Energy used to seal data (v1.0.1): Sealing is the process of generating SNARK proofs for a data sector which will allow an SP to prove that they are continuing to store that data over time, and is one of the components of energy use of the Filecoin network. Energy use due to sealing is estimated by multiplying the increase in storage capacity over a given time period by a constant value as described in the methodology. Bounds and estimate come from different values of this constant. Network view: Total electrical power used to seal data for the entire Filecoin network. Storage Provider (SP) view: Electrical power used by this SP to seal data. Model: "id": 3 or "code_name": "SealingEnergyModelv_1_0_1"

Energy used to store data (v1.0.1): The energy used to store data over time, which is a component of the energy used by the Filecoin network. Storage energy use is estimated by multiplying storage capacity by a constant value. Bounds and estimate come from different values of this constant. Network view: Total electrical power used to store all data on the Filecoin network. Storage Provider (SP) view: Electrical power used by this SP to store data. Model: "id": 4 or "code_name": "StorageEnergyModelv_1_0_1"

Cumulative Energy Use (v1.0.1): Total amount of energy used during a time period in kWh. Model: "id": 5 or "code_name": "CumulativeEnergyModel_v_1_0_1"

Cumulative renewable energy purchases: Cumulative renewable energy certificate (REC) purchases over time. Model: "id": 6 or "code_name": "RenewableEnergyModel"

Data storage capacity added per day: Network view: New data storage capacity added to Filecoin’s decentralized storage network (sealed) per day. Storage Provider (SP) view: The amount of new data storage contributed to the network (sealed) by this SP per day. Model: "id": 7 or "code_name": "SealedModel"

Data storage capacity: Network view: The total amount of data storage capacity contributed to Filecoin’s decentralized storage network, based on on-chain proofs. Storage Provider (SP) view: The amount of data storage contributed by this SP, based on on-chain proofs. Model: "id": 8 or "code_name": "CapacityModel"

Energy Consumption: Daily, weekly and monthly data granularity

This endpoint provides energy consumption data for selected data model grouped on a daily, weekly or monthly scale.

Energy consumption grouped on a daily, weekly and monthly scale for selected model, date range and Storage Provider

GET https://api.filgreen.d.interplanetary.one/models/model

Query Parameters

Name

Type

Description

id*

Integer

Id of the data model. (either "id" or associated "code_name" query parameter have to be provided)

code_name*

Code name of the data model, see 'Available data models' above. (either "id" or associated "code_name" query parameter have to be provided)

filter

Data granulation. Possible values are: "day", "week" or "month". If not provided "day" is considered as default value.

miner

String

Miner Id (e.g. f01234). If not listed data is provided without filtering per miner Id.

start

Date / String

ISO 8601 formatted start date. If not provided data points are listed from the epoch 0.

end

Date / String

ISO 8601 formatted end date. If not provided data points are listed up to the most recent measurement.

{
    "id": "0",
    "code_name": "TotalEnergyModelv_1_0_1",
    "name": "Energy consumption rate (v1.0.1)",
    "category": "energy",
    "x": "time",
    "y": "kW",
    "version": 0,
    "filter": "day",
    "data": [
        {
            "title": "Lower bound",
            "data": [
                {
                    "value": "31894.361954900576",
                    "start_date": "2022-04-29T00:00:00.000Z",
                    "end_date": "2022-04-29T23:59:59.999Z"
                },
                {
                    "value": "31775.267922347760",
                    "start_date": "2022-04-30T00:00:00.000Z",
                    "end_date": "2022-04-30T23:59:59.999Z"
                }
            ]
        },
        {
            "title": "Estimate",
            "data": [
                {
                    "value": "171561.258677004376",
                    "start_date": "2022-04-29T00:00:00.000Z",
                    "end_date": "2022-04-29T23:59:59.999Z"
                },
                {
                    "value": "170551.946689708060",
                    "start_date": "2022-04-30T00:00:00.000Z",
                    "end_date": "2022-04-30T23:59:59.999Z"
                }
            ]
        },
        {
            "title": "Upper bound",
            "data": [
                {
                    "value": "473751.138657113246",
                    "start_date": "2022-04-29T00:00:00.000Z",
                    "end_date": "2022-04-29T23:59:59.999Z"
                },
                {
                    "value": "471916.373850792235",
                    "start_date": "2022-04-30T00:00:00.000Z",
                    "end_date": "2022-04-30T23:59:59.999Z"
                }
            ]
        }
    ]
} // Response
}

Energy Consumption: All data points

This endpoint provides all measured energy consumption data points for selected data model.