Getting started (5 min)

This page presents basic queries that can be used to retrieve impacts.

You use curl in command line to query Boavizta demo (public) API.

💡 You can format the results by using jq (curl -X 'GET' 'https://api.boavizta.org/v1/server/model?archetype=dellR740' | jq)

Get the impacts of a dellR740 server

This is the simplest possible query. It returns the impacts of a standard (i.e. predefined) server configuration (dellR740).

Query:

# Query the data for `dellR740`
curl -X 'GET' \
  'https://api.boavizta.org/v1/server/model?archetype=dellR740&verbose=false' \
  -H 'accept: application/json'

Results:

{
  "gwp": {
    "manufacture": 970,
    "use": 2100,
    "unit": "kgCO2eq"
  },
  "pe": {
    "manufacture": 13000,
    "use": 71020,
    "unit": "MJ"
  },
  "adp": {
    "manufacture": 0.15,
    "use": 0.000354,
    "unit": "kgSbeq"
  }
}

Get the values used to measure the impacts of each component

This is the same query as before. However, you add the verbose=true flag to get the impacts of each of its components and the value of the attributes used for the calculation.

Query:

# Query the data for `dellR740`
curl -X 'GET' \
  'https://api.boavizta.org/v1/server/model?archetype=dellR740&verbose=true' \
  -H 'accept: application/json'

It returns :

• The total impacts of manufacturing (gwp, pe, adp) for each component (like RAM, CPU, SSD a.s.o)
• The impacts (gwp, pe, adp) of usage at server level for one year
• The impacts (gwp, pe, adp) of usage for CPU and RAM for one year
• The value of the attributes used for the calculation for each component (i.e. the detailed configuration)

{
  "impacts": {
    "gwp": {
      "manufacture": 970,
      "use": 2100,
      "unit": "kgCO2eq"
    },
    "pe": {
      "manufacture": 13000,
      "use": 71020,
      "unit": "MJ"
    },
    "adp": {
      "manufacture": 0.15,
      "use": 0.000354,
      "unit": "kgSbeq"
    }
  },
  "verbose": {
    "ASSEMBLY-1": {
      "units": 1,
      "manufacture_impacts": {
        "gwp": {
          "value": 6.68,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 68.6,
          "unit": "MJ"
        },
        "adp": {
          "value": 1.41e-06,
          "unit": "kgSbeq"
        }
      }
    },
    "CPU-1": {
      "units": 2,
      "manufacture_impacts": {
        "gwp": {
          "value": 21.7,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 325,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.02,
          "unit": "kgSbeq"
        }
      },
      "core_units": {
        "value": 24,
        "unit": "none",
        "status": "INPUT",
        "source": null
      },
      "die_size_per_core": {
        "value": 0.245,
        "unit": "mm2",
        "status": "INPUT",
        "source": null
      },
      "USAGE": {
        "usage_impacts": {
          "gwp": {
            "value": 610,
            "unit": "kgCO2eq"
          },
          "pe": {
            "value": 20550,
            "unit": "MJ"
          },
          "adp": {
            "value": 0.000102,
            "unit": "kgSbeq"
          }
        },
        "hours_electrical_consumption": {
          "value": 182.23023303189055,
          "unit": "W",
          "status": "COMPLETED",
          "source": null
        },
        "time_workload": {
          "value": 50,
          "unit": "%",
          "status": "DEFAULT",
          "source": null
        },
        "usage_location": {
          "value": "EEE",
          "unit": "CodSP3 - NCS Country Codes - NATO",
          "status": "DEFAULT",
          "source": null
        },
        "adp_factor": {
          "value": 6.42e-08,
          "unit": "KgSbeq/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "ADEME BASE IMPACT"
          }
        },
        "gwp_factor": {
          "value": 0.38,
          "unit": "kgCO2e/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "https://www.sciencedirect.com/science/article/pii/S0306261921012149 : \nAverage of 27 european countries"
          }
        },
        "pe_factor": {
          "value": 12.874,
          "unit": "MJ/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "ADPf / (1-%renewable_energy)"
          }
        },
        "use_time": {
          "value": 8760,
          "unit": "hours",
          "status": "DEFAULT",
          "source": null
        },
        "params": {
          "value": {
            "a": 171.2,
            "b": 0.0354,
            "c": 36.89,
            "d": -10.13
          },
          "unit": "none",
          "status": "DEFAULT",
          "source": null
        }
      }
    },
    "RAM-1": {
      "units": 12,
      "manufacture_impacts": {
        "gwp": {
          "value": 45,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 560,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.0028,
          "unit": "kgSbeq"
        }
      },
      "capacity": {
        "value": 32,
        "unit": "GB",
        "status": "INPUT",
        "source": null
      },
      "density": {
        "value": 1.79,
        "unit": "GB/cm2",
        "status": "INPUT",
        "source": null
      },
      "USAGE": {
        "usage_impacts": {
          "gwp": {
            "value": 30,
            "unit": "kgCO2eq"
          },
          "pe": {
            "value": 1025,
            "unit": "MJ"
          },
          "adp": {
            "value": 5.11e-06,
            "unit": "kgSbeq"
          }
        },
        "hours_electrical_consumption": {
          "value": 9.088,
          "unit": "W",
          "status": "COMPLETED",
          "source": null
        },
        "time_workload": {
          "value": 50,
          "unit": "%",
          "status": "DEFAULT",
          "source": null
        },
        "usage_location": {
          "value": "EEE",
          "unit": "CodSP3 - NCS Country Codes - NATO",
          "status": "DEFAULT",
          "source": null
        },
        "adp_factor": {
          "value": 6.42e-08,
          "unit": "KgSbeq/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "ADEME BASE IMPACT"
          }
        },
        "gwp_factor": {
          "value": 0.38,
          "unit": "kgCO2e/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "https://www.sciencedirect.com/science/article/pii/S0306261921012149 : \nAverage of 27 european countries"
          }
        },
        "pe_factor": {
          "value": 12.874,
          "unit": "MJ/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "ADPf / (1-%renewable_energy)"
          }
        },
        "use_time": {
          "value": 8760,
          "unit": "hours",
          "status": "DEFAULT",
          "source": null
        },
        "params": {
          "value": {
            "a": 9.088
          },
          "unit": "none",
          "status": "COMPLETED",
          "source": "(ram_electrical_factor_per_go : 0.284) * (ram_electrical_factor_per_go: 32) "
        }
      }
    },
    "SSD-1": {
      "units": 1,
      "manufacture_impacts": {
        "gwp": {
          "value": 24,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 293,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.0011,
          "unit": "kgSbeq"
        }
      },
      "capacity": {
        "value": 400,
        "unit": "GB",
        "status": "INPUT",
        "source": null
      },
      "density": {
        "value": 50.6,
        "unit": "GB/cm2",
        "status": "INPUT",
        "source": null
      }
    },
    "POWER_SUPPLY-1": {
      "units": 2,
      "manufacture_impacts": {
        "gwp": {
          "value": 72.7,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 1050,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.025,
          "unit": "kgSbeq"
        }
      },
      "unit_weight": {
        "value": 2.99,
        "unit": "kg",
        "status": "INPUT",
        "source": null
      }
    },
    "CASE-1": {
      "units": 1,
      "manufacture_impacts": {
        "gwp": {
          "value": 150,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 2200,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.0202,
          "unit": "kgSbeq"
        }
      },
      "case_type": {
        "value": "rack",
        "unit": "none",
        "status": "INPUT",
        "source": null
      }
    },
    "MOTHERBOARD-1": {
      "units": 1,
      "manufacture_impacts": {
        "gwp": {
          "value": 66.1,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 836,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.00369,
          "unit": "kgSbeq"
        }
      }
    },
    "USAGE": {
      "usage_impacts": {
        "gwp": {
          "value": 2100,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 71020,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.000354,
          "unit": "kgSbeq"
        }
      },
      "hours_electrical_consumption": {
        "value": 629.7768998648289,
        "unit": "W",
        "status": "COMPLETED",
        "source": null
      },
      "usage_location": {
        "value": "EEE",
        "unit": "CodSP3 - NCS Country Codes - NATO",
        "status": "DEFAULT",
        "source": null
      },
      "adp_factor": {
        "value": 6.42e-08,
        "unit": "KgSbeq/kWh",
        "status": "COMPLETED",
        "source": {
          "1": "ADEME BASE IMPACT"
        }
      },
      "gwp_factor": {
        "value": 0.38,
        "unit": "kgCO2e/kWh",
        "status": "COMPLETED",
        "source": {
          "1": "https://www.sciencedirect.com/science/article/pii/S0306261921012149 : \nAverage of 27 european countries"
        }
      },
      "pe_factor": {
        "value": 12.874,
        "unit": "MJ/kWh",
        "status": "COMPLETED",
        "source": {
          "1": "ADPf / (1-%renewable_energy)"
        }
      },
      "use_time": {
        "value": 8760,
        "unit": "hours",
        "status": "DEFAULT",
        "source": null
      },
      "other_consumption_ratio": {
        "value": 0.33,
        "unit": "ratio /1",
        "status": "DEFAULT",
        "source": null
      }
    }
  }
}

Retrieve the impacts of a custom server

In this query, you provide a specific configuration of the machine. Missing attributes or component will be replaced by default ones.

The API returns impacts, to reflect your own server configuration.

Query :

curl -X 'POST' \
  'https://api.boavizta.org/v1/server/?verbose=false' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": {
    "type": "rack"
  },
  "configuration": {
    "cpu": {
      "units": 2,
      "core_units": 12,
      "die_size_per_core": 0.245
    },
    "ram": [
      {
        "units": 12,
        "capacity": 64,
        "density": 1.79
      }
    ],
    "disk": [
      {
        "units": 4,
        "type": "ssd",
        "capacity": 400,
        "density": 50.6
      }
    ],
    "power_supply": {
      "units": 2,
      "unit_weight": 2.99
    }
  }
}'

Result :

{
  "gwp": {
    "manufacture": 1500,
    "use": 2600,
    "unit": "kgCO2eq"
  },
  "pe": {
    "manufacture": 19000,
    "use": 87380,
    "unit": "MJ"
  },
  "adp": {
    "manufacture": 0.17,
    "use": 0.000436,
    "unit": "kgSbeq"
  }
}

Retrieve the impacts with from a custom power consumption

In this query, we use the default server configuration, but provide a specific usage of the machine.

In this specific case the average power consumption of the machine is known (`hours_electrical_consumptions)

The API returns impacts, updated to reflect your own server usage.

Query :

curl -X 'POST' \
  'https://api.boavizta.org/v1/server/?verbose=true' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": {},
  "configuration": {},
  "usage":{
     "years_use_time": 1,
     "days_use_time": 1,
     "hours_use_time": 1,
     "usage_location": "FRA",
     "hours_electrical_consumption": 250
    }
  }'

• The server is evaluated with the specific impacts of the French electrical grid.
• The server is evaluated for a usage of 1 year, 1 day, 1 hour. It corresponds to 8785 hours.
• The average electrical consumption per hour is 250 W/hour

Result :

{
  "impacts": {
    "gwp": {
      "manufacture": 3300,
      "use": 220,
      "unit": "kgCO2eq"
    },
    "pe": {
      "manufacture": 42000,
      "use": 24800,
      "unit": "MJ"
    },
    "adp": {
      "manufacture": 0.23,
      "use": 0.000107,
      "unit": "kgSbeq"
    }
  },
  "verbose": {
   ...
    "USAGE": {
      "usage_impacts": {
        "gwp": {
          "value": 220,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 24800,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.000107,
          "unit": "kgSbeq"
        }
      },
      "hours_electrical_consumption": {
        "value": 250,
        "unit": "W",
        "status": "INPUT",
        "source": null
      },
      "usage_location": {
        "value": "FRA",
        "unit": "CodSP3 - NCS Country Codes - NATO",
        "status": "INPUT",
        "source": null
      },
      "adp_factor": {
        "value": 4.86e-08,
        "unit": "KgSbeq/kWh",
        "status": "COMPLETED",
        "source": {
          "43": "ADEME BASE IMPACT"
        }
      },
      "gwp_factor": {
        "value": 0.098,
        "unit": "kgCO2e/kWh",
        "status": "COMPLETED",
        "source": {
          "43": "https://www.sciencedirect.com/science/article/pii/S0306261921012149"
        }
      },
      "pe_factor": {
        "value": 11.289,
        "unit": "MJ/kWh",
        "status": "COMPLETED",
        "source": {
          "43": "ADPf / (1-%renewable_energy)"
        }
      },
      "use_time": {
        "value": 8785,
        "unit": "hours",
        "status": "INPUT",
        "source": null
      }
    }
  }
}

Retrieve the impacts with from a custom workload

In this query, we use the default server configuration, but provide a specific usage of the machine.

In this case the average is unknown. We use the level of workload (time_workload) of the machine as a proxy for the power consumption.

Query :

curl -X 'POST' \
  'https://api.boavizta.org/v1/server/?verbose=true' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": {},
  "configuration": {},
  "usage":{
     "years_use_time": 1,
     "days_use_time": 1,
     "hours_use_time": 1,
     "usage_location": "FRA",
     "time_workload": 90
    }
  }'

• The API will create a consumption profile based on the default characteristics and apply it for an average level of workload of 90%

Result :

{
  "impacts": {
    "gwp": {
      "manufacture": 3300,
      "use": 820,
      "unit": "kgCO2eq"
    },
    "pe": {
      "manufacture": 42000,
      "use": 93940,
      "unit": "MJ"
    },
    "adp": {
      "manufacture": 0.23,
      "use": 0.000404,
      "unit": "kgSbeq"
    }
  },
   ...
    "CPU-1": {
      ...
      "USAGE": {
        "usage_impacts": {
          "gwp": {
            "value": 820,
            "unit": "kgCO2eq"
          },
          "pe": {
            "value": 27940,
            "unit": "MJ"
          },
          "adp": {
            "value": 0.000139,
            "unit": "kgSbeq"
          }
        },
        "hours_electrical_consumption": {
          "value": 247.0598413289702,
          "unit": "W",
          "status": "COMPLETED",
          "source": null
        },
        "time_workload": {
          "value": 90,
          "unit": "%",
          "status": "INPUT",
          "source": null
        },
        "usage_location": {
          "value": "FRA",
          "unit": "CodSP3 - NCS Country Codes - NATO",
          "status": "INPUT",
          "source": null
        },
        "adp_factor": {
          "value": 6.42e-08,
          "unit": "KgSbeq/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "ADEME BASE IMPACT"
          }
        },
        "gwp_factor": {
          "value": 0.38,
          "unit": "kgCO2e/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "https://www.sciencedirect.com/science/article/pii/S0306261921012149 : \nAverage of 27 european countries"
          }
        },
        "pe_factor": {
          "value": 12.874,
          "unit": "MJ/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "ADPf / (1-%renewable_energy)"
          }
        },
        "use_time": {
          "value": 8785,
          "unit": "hours",
          "status": "INPUT",
          "source": null
        },
        "params": {
          "value": {
            "a": 171.2,
            "b": 0.0354,
            "c": 36.89,
            "d": -10.13
          },
          "unit": "none",
          "status": "DEFAULT",
          "source": null
        }
      }
    },
    "RAM-1": {
      ...
      "USAGE": {
        "usage_impacts": {
          "gwp": {
            "value": 30,
            "unit": "kgCO2eq"
          },
          "pe": {
            "value": 1028,
            "unit": "MJ"
          },
          "adp": {
            "value": 5.13e-06,
            "unit": "kgSbeq"
          }
        },
        "hours_electrical_consumption": {
          "value": 9.088,
          "unit": "W",
          "status": "COMPLETED",
          "source": null
        },
        "time_workload": {
          "value": 90,
          "unit": "%",
          "status": "INPUT",
          "source": null
        },
        "usage_location": {
          "value": "FRA",
          "unit": "CodSP3 - NCS Country Codes - NATO",
          "status": "INPUT",
          "source": null
        },
        "adp_factor": {
          "value": 6.42e-08,
          "unit": "KgSbeq/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "ADEME BASE IMPACT"
          }
        },
        "gwp_factor": {
          "value": 0.38,
          "unit": "kgCO2e/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "https://www.sciencedirect.com/science/article/pii/S0306261921012149 : \nAverage of 27 european countries"
          }
        },
        "pe_factor": {
          "value": 12.874,
          "unit": "MJ/kWh",
          "status": "COMPLETED",
          "source": {
            "1": "ADPf / (1-%renewable_energy)"
          }
        },
        "use_time": {
          "value": 8785,
          "unit": "hours",
          "status": "INPUT",
          "source": null
        },
        "params": {
          "value": {
            "a": 9.088
          },
          "unit": "none",
          "status": "COMPLETED",
          "source": "(ram_electrical_factor_per_go : 0.284) * (ram_electrical_factor_per_go: 32) "
        }
      }
    },
    ...
    "USAGE": {
      "usage_impacts": {
        "gwp": {
          "value": 820,
          "unit": "kgCO2eq"
        },
        "pe": {
          "value": 93940,
          "unit": "MJ"
        },
        "adp": {
          "value": 0.000404,
          "unit": "kgSbeq"
        }
      },
      "hours_electrical_consumption": {
        "value": 947.2681379350607,
        "unit": "W",
        "status": "COMPLETED",
        "source": null
      },
      "time_workload": {
        "value": 90,
        "unit": "%",
        "status": "INPUT",
        "source": null
      },
      "usage_location": {
        "value": "FRA",
        "unit": "CodSP3 - NCS Country Codes - NATO",
        "status": "INPUT",
        "source": null
      },
      "adp_factor": {
        "value": 4.86e-08,
        "unit": "KgSbeq/kWh",
        "status": "COMPLETED",
        "source": {
          "43": "ADEME BASE IMPACT"
        }
      },
      "gwp_factor": {
        "value": 0.098,
        "unit": "kgCO2e/kWh",
        "status": "COMPLETED",
        "source": {
          "43": "https://www.sciencedirect.com/science/article/pii/S0306261921012149"
        }
      },
      "pe_factor": {
        "value": 11.289,
        "unit": "MJ/kWh",
        "status": "COMPLETED",
        "source": {
          "43": "ADPf / (1-%renewable_energy)"
        }
      },
      "use_time": {
        "value": 8785,
        "unit": "hours",
        "status": "INPUT",
        "source": null
      },
      "other_consumption_ratio": {
        "value": 0.33,
        "unit": "ratio /1",
        "status": "DEFAULT",
        "source": null
      }
    }
  }
}

For further information see : The explanation page on servers