Use the impact model with the API
Link to the Swagger: https://co2-algorithm-service.greenspector.com/swagger/index.html
1. Modular composition of the model
The Greenspector impact model is composed of bricks which represent the footprint steps: client, network, server.
Requests | Impact bricks |
|---|---|
/client/battery | Battery-operated terminal: smartphone, tablet, laptop. It is a battery use allocation model. Is is mainly based on the manufacture impact allocation depending on the energy consumption of the equipment.
|
/client/usageTime | Terminal operating on power supply: desktop PC, TV… It is a time-of-use allocation model. It is a classic model used in LCA (Life Cycle Assessment) and impact analysis. It is mainly based on the manufacture impact allocation depending on the equipment usage time.
|
/custom | Free choice among the different bricks and their number (ex: impact with a smartphone, one type of network, two video servers and one classic server)
|
/network | New network brick. The impact is calculated according to the data exchanged and the network type used: 2g3g, 4g5g, adsl, fibre, ethernet, hotspot, wifi.
|
/networkOld | Old network brick. The impact is calculated according to the data exchanged.
|
/server/bandwidth | It is a bandwidth allocation model. It is dedicated to servers which process important information flows (Content Delivery Network or video server).
|
/server/request | It is a request allocation model. It is appropriate for classic servers. The modeling is done by taking the number of HTTP requests as input.
|
Here is a diagram showing the different impact bricks:
Each brick can be called independently, creating a modular composition. A few examples:
For video streaming on smartphone: Smartphone > New Generation GSM > Video server
For a website visited on a company desktop PC: Desktop PC > LAN Ethernet > Simple server
For a connected object with several servers: Custom terminal operating on power supply > LAN Wifi > CDN > LAN Ethernet > Simple server
Each brick can be found in the API:
2. Brick configuration
Each brick can be configured with different information:
The energy mix (customImpactOutput): To calculate the impact of use, it is necessary to enter a mix.
The input data (dataInput): This is the measured data. It can be energy, exchanged data, test duration, number of HTTP request…
A configuration distribution (xTypes): For some bricks, it is possible to configure a distribution between the different equipments or network used.
The model parameters (parameters): These are the model assumptions. They can be technical (PUE…), linked to usage (desktop PC usage time)… They are optional.
Metadata (metadata): A name and a version can be added. They are optional.
The model parameters are optional. If they are not given, the model uses data by default. We will see that completing these parameters allow to be more precise.
Example in the API:
3. Output data
The results are displayed as follows:
Impact distribution (breakDown): ratio between the impact of manufacturing and use
3 result blocks: results divided by footprint steps (device, network, server)
For each step, 3 values are given: lower bound, central value and upper bound. It gives a result with a margin of uncertainty
Units used: carbon in gCO2, water in litres, surface in cm²
"carbon": {
"breakDown": {
"fabrication": 20,
"usage": 80
},
"deviceFootprint": {
"centralValue": 0.12,
"lowerBound": 0.1,
"upperBound": 0.2
},
"networkFootprint": {
"centralValue": 0.12,
"lowerBound": 0.1,
"upperBound": 0.2
},
"serverFootprint": {
"centralValue": 0.12,
"lowerBound": 0.1,
"upperBound": 0.2
}
},
4. Details of requests
4.1. Request /customImpact
It calculates the energy mix impact based on location.
The energy mix is obtained with the following units:
Carbon in gEqCO2/kWh
Water in L/MWh
Surface in W/m²
Input parameter | Description | Unit |
|---|---|---|
france | Percentage of location in France | % |
world | Percentage of location in the world | % |
The result of this request must be placed in the customImpactOutput parameter of the other requests. It is composed of trapezes of 4 values. It allows uncertainties to be taken into account.
4.2. Request /client/battery
Input parameter | Description | Unit |
|---|---|---|
customImpactOutput
| Custom impacts in carbon, water and surface* (optional, world values by default) |
|
platDischarge | Phone discharge | mAh |
referenceDischarge | Reference discharge speed of the tested phone (optional) | μAh/s |
userTypes :
| Percentage of smartphones, tablets and PC among users. The sum must equal 100%. | % |
* : The custom impacts in carbon, water and surface are obtained with the /customImpact request, specifying the location.
4.2. Request /client/usageTime
Input parameter | Description | Unit |
|---|---|---|
customImpactOutput :
| Custom impacts in carbon, water and surface* (optional, world values by default) |
|
testDuration | Duration of use | s |
blockName | Name of the device (optional) | / |
version | Version of the device (optional) | / |
dailyActiveTime | Daily device activity (ex: 7 hours a day) (optional) | hours |
hardwareManufacture | Impact of hardware manufacturing (optional) |
|
hardwareType | Device type : desktopPc, custom, stb (set-top box), stbLight, tv, console | / |
lifeExpectancy | Life expectancy of the device (optional) | years |
energy | Phone discharge (optional) | Wh |
* : The custom impacts in carbon, water and surface are obtained with the /customImpact request, specifying the location.
4.3. Request /network
Input parameter | Description | Unit |
|---|---|---|
customImpactOutput :
| Custom impacts in carbon, water and surface* (optional, world values by default) |
|
dataNetwork | Network data exchanged by the phone | Mo |
testDuration | Duration of use | s |
networkTypes :
| Percentage of the different networks. The sum must equal 100%.
The network types lanEthernet, lanHotspot and lanWifi correspond to a corporate network. The network types wiredFibre and wiredXdsl correspond to a personal network. | % |
dailyActiveTimeCpe | Daily activity of the cpe (ex: 5 hours a day) (optional) Cpe means “customer premises equipment”. It corresponds to a network equipment used in an individual home. It can be a box. This parameter has an impact only if the network types wiredFibre or wiredXdsl are used. | hours |
lifeExpectancySwitch | Life expectancy of the switch (ex: 10 years) (optional) A switch is a network equipment used in a company. This parameter has an impact only if the network types lanEthernet, lanHotspot or lanWifi are used. | years |
yearlyActiveTimeSwitch | Annual switch activity (ex: 2200 hours a year) (optional) A switch is a network equipment used in a company. This parameter has an impact only if the network types lanEthernet, lanHotspot or lanWifi are used. | hours |
* : The custom impacts in carbon, water and surface are obtained with the /customImpact request, specifying the location.
4.4. Request /networkOld
Input parameter | Description | Unit |
|---|---|---|
customImpactOutput :
| Custom impacts in carbon, water and surface* (optional, world values by default) |
|
dataNetwork | Network data exchanged by the phone | Mo |
* : The custom impacts in carbon, water and surface are obtained with the /customImpact request, specifying the location.
4.5. Request /server/bandwitch
Input parameter | Description | Unit |
|---|---|---|
customImpactOutput :
| Custom impacts in carbon, water and surface* (optional, world values by default) |
|
dataNetwork | Network data exchanged by the phone | Mo |
testDuration | Duration of use | s |
numberOfServers | Number of servers used to provide the service (optional) | / |
peakServerLoad | Peak server load (optional) It corresponds to the server sizing. This is the server load in CPU when there are a maximum of users. A peak server load of 50% means that the server is used at half its capacity. | % |
pue | Power usage effectiveness (optional) | / |
serverBandwidth | Server bandwidth (optional) | Go/s |
* : The custom impacts in carbon, water and surface are obtained with the /customImpact request, specifying the location.
4.6. Request /server/request
Input parameter | Description | Unit |
|---|---|---|
customImpactOutput :
| Custom impacts in carbon, water and surface* (optional, world values by default) |
|
serverTypes :
| Percentage of the different servers. The sum must equal 100%.
| %
|
dataNetwork | Network data exchanged by the phone | Mo |
reqNetwork | Number of HTTP requests | / |
pue | Power usage effectiveness (optional) | / |
* : The custom impacts in carbon, water and surface are obtained with the /customImpact request, specifying the location.
5. Connection to other tools and other methodologies
Greenspector measurement tools use this API.
If you have another measurement tool, you can use this API.
The API can also be used without measurement, using the default values.
Moreover, within the scope of LCA (Life Cycle Assessment), the API can be used for the LCI (Life Cycle Inventory).
6. Uncertainty management
The algorithm allows uncertainties to be propagated. Launching the algorithm with the default parameters gives high uncertainties. Completing these parameters allows to reduce uncertainties.
Example: Accuracy of the results on a PC
7. Why use the Greenspector impact API?
Based on hundreds of parameters and on a spread of uncertainties, the Greenspector impact model gives precise results. It can be used with Greenspector measurement tools or digital assessment environments. It can also be integrated in LCA (Life Cycle Assessment) type assessments.