⚡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

200: OK JSON response

[
    {
        "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.

200: OK JSON response

{
    "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.

Energy consumption

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

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)
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.
offset	Integer	Number of data points to skip from the beginning of the record set. Default 0.
limit	Integer	Maximal number of data points to be listed. Default 10000.

200: OK JSON response

{
  "fields": [
    "epoch",
    "total_energy_kW_lower",
    "total_energy_kW_estimate",
    "total_energy_kW_upper",
    "timestamp"
  ],
  "data": [
    {
      "epoch": "1423800",
      "total_energy_kW_lower": "26561.709211124736",
      "total_energy_kW_estimate": "142666.944194007936",
      "total_energy_kW_upper": "394504.605809705056",
      "timestamp": "2022-01-01T00:00:00.000Z"
    },
    {
      "epoch": "1423801",
      "total_energy_kW_lower": "33665.494160344832",
      "total_energy_kW_estimate": "196408.026620076032",
      "total_energy_kW_upper": "502793.474799859072",
      "timestamp": "2022-01-01T00:00:30.000Z"
    },
    {
      "epoch": "1423802",
      "total_energy_kW_lower": "24310.747738816768",
      "total_energy_kW_estimate": "125638.018984010368",
      "total_energy_kW_upper": "360191.320487680928",
      "timestamp": "2022-01-01T00:01:00.000Z"
    },
    {
      "epoch": "1423803",
      "total_energy_kW_lower": "26620.212637369856",
      "total_energy_kW_estimate": "143109.417155747456",
      "total_energy_kW_upper": "395396.401709311776",
      "timestamp": "2022-01-01T00:01:30.000Z"
    },
    {
      "epoch": "1423804",
      "total_energy_kW_lower": "24778.503308768000",
      "total_energy_kW_estimate": "129176.600096249600",
      "total_energy_kW_upper": "367321.696158196800",
      "timestamp": "2022-01-01T00:02:00.000Z"
    },
    {
      "epoch": "1423805",
      "total_energy_kW_lower": "24456.941042341376",
      "total_energy_kW_estimate": "126743.912678130176",
      "total_energy_kW_upper": "362419.851969575296",
      "timestamp": "2022-01-01T00:02:30.000Z"
    },
    {
      "epoch": "1423806",
      "total_energy_kW_lower": "23258.369123417344",
      "total_energy_kW_estimate": "117676.527420118144",
      "total_energy_kW_upper": "344149.023870830624",
      "timestamp": "2022-01-01T00:03:00.000Z"
    },
    {
      "epoch": "1423807",
      "total_energy_kW_lower": "27906.524038613504",
      "total_energy_kW_estimate": "152840.442591807104",
      "total_energy_kW_upper": "415004.693759300384",
      "timestamp": "2022-01-01T00:03:30.000Z"
    },
    {
      "epoch": "1423808",
      "total_energy_kW_lower": "27000.292853051136",
      "total_energy_kW_estimate": "145984.641783342336",
      "total_energy_kW_upper": "401190.255044203456",
      "timestamp": "2022-01-01T00:04:00.000Z"
    },
    {
      "epoch": "1423809",
      "total_energy_kW_lower": "27175.705275236096",
      "total_energy_kW_estimate": "147311.627765050496",
      "total_energy_kW_upper": "403864.205879485216",
      "timestamp": "2022-01-01T00:04:30.000Z"
    }
  ]
}