Skip to content

Analytics

Guide on accessing analytics functionality through the HTTP API.

Overview

Preliminaries

The examples provided in this article partly build on each other. For the sake of brevity, examples of imports or variable definitions are only shown once and left out in subsequent examples.

To execute the examples provided in this tutorial, the following is needed:

  • A valid login (username and password) to the aedifion.io platform. If you do not have a login yet, please contact us regarding a demo login. The login used in the example will not work!
  • A project with mapped components on which analyses have been configured and successfully computed.
  • Optionally, a working installation of Python or Curl.

Basic concepts

We briefly revise the basic terminology used in this tutorial. Make sure to check our Glossary when something seems unclear to you.

  • Abstract components: aedifion provides a set of curated components that abstractly model the (expected) functioning of various physical or virtual technical building equipment such as boilers, heat pumps, control loops, rooms, etc. The API refers to these abstract components simply as component (see Component-tagged API resources).
  • Pins: Each component has a set of pins that are placeholders for a real component's datapoints. E.g., the heat pump component has pins for its supply and return temperature.
  • Attributes: Most components have attributes that can be specified and describe certain characteristics specific to the component. E.g., the room component has an attribute for the schedule of the room.
  • Mapped components: The process of attaching real datapoints collected from a real building, factory, district, etc. to a component is referred to as mapping. Mapping creates a component instance that holds mapped data points and is bound to a project. On the API, we refer to a mapped component as a componentInProject (see Project-tagged API resources).
  • Analysis functions: aedifion provides a suite of algorithms to analyze building performance. The API calls these analysis functions. Each analysis function can be applied to one or more components. E.g., an analysis of the temperature spread might apply only to the heat pump component, while an analysis of duty cycles might apply to any physical, active component.
  • Analysis instance: To run an analysis on real data, a configuration of which analysis functions are applied to which mapped component is required first. By this configuration, an analysis function is instantiated (similar to a component that is mapped) and becomes an analysis instance. The configured instance can subsequently be executed on arbitrary time ranges, e.g., days, weeks, months, or whole years.
  • Analysis result: Each execution of an instance on a time range provides a single result object that can be queried using its unique reference.
  • IDs All components, functions, pins, and attributes have numeric and alphanumeric IDs that can be used to identify them. The numeric IDs are assigned by the server and may vary from server to server or between software releases. In contrast, the alphanumeric IDs remain the same, regardless of the analytics version and server.

Abstract components

Let's first explore the available abstract component models. We provide information about the details of these models in the engineering part of this documentation. In this article, we focus on developers' needs and use the HTTP API's GET /v2/components endpoint to query the most basic information about them.

import requests

api_url = 'https://api.aedifion.io'
auth_john = ("john.doe@aedifion.com", "s3cr3tp4ssw0rd")
r = requests.get(f"{api_url}/v2/components", auth=auth_john)
print(r.text)
curl "https://api.aedifion.io/v2/components"
    -X GET
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Component tag, then the GET /v2/components endpoint (blue).
  4. Click "Try it out!".
  5. Inspect the response body and code.

The response is a JSON-formatted list of the available components. Each component has a unique alphanumeric ID, a unique numerical ID, an English and German name.

[
  {
    "alphanumeric_id": "TH_CTRL_LOO",
    "id": 21,
    "nameDE": "thermischer Regelkreis",
    "nameEN": "Thermal control loop"
  },
  {
    "alphanumeric_id": "WST",
    "id": 22,
    "nameDE": "Wetterstation",
    "nameEN": "Weather station"
  },
  {
    "alphanumeric_id": "BOI",
    "id": 15,
    "nameDE": "Kessel",
    "nameEN": "Boiler"
  },

  {
    "alphanumeric_id": "ROOM",
    "id": 20,
    "nameDE": "Raum",
    "nameEN": "Room"
  },

  ...

  { "alphanumeric_id": "HM",
    "id": 18, 
    "nameDE": "Wärmezähler",
    "nameEN": "Heat meter"
  },
  {
    "alphanumeric_id": "CHP",
    "id": 16,
    "nameDE": "Kraftwärmekopplung",
    "nameEN": "Combined heat and power"
  }
]

Component pins and attributes

Components have pins and attributes. On abstract components these are placeholders that are filled with real datapoints (pins) and meta information for the analysis (attributes) in mapped components. To view pins or attribute placeholders for abstract components, the GET /v2/component/{component_id}/pins and GET /v2/component/{component_id}/attributeDefinitions endpoints are used.

Let's have a closer look at the thermal control loop component with ID = 21.

r = requests.get(f"{api_url}/v2/component/21/pins", auth=auth_john)
print(r.text)

r = requests.get(f"{api_url}/v2/component/21/attributeDefinitions",
                 auth=auth_john)
print(r.text)

curl "https://api.aedifion.io/v2/component/21/pins" 
    -X GET
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd
curl "https://api.aedifion.io/v2/component/21/attributeDefinitions" 
    -X GET
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd

  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Component tag, then the GET /v2/component/{component_id}/pins or GET /v2/component/{component_id}/attributeDefinitions endpoint (blue).
  4. Click "Try it out!".
  5. Inspect the response body and code.

The thermal control loop component has nine pin placeholders (analytics v1.3.0). Note that not all analysis functions require all pins to be filled and one group of pins may make another group of pins redundant. Each pin has a unique alphanumeric ID, a unique numerical ID as well as English and German names. The "location" is used for graphical interfaces. The "pin_attributes" describe expected properties of this pin which are used in combination with the artificial intelligence to map data points to those pins.

[
  {
    "alphanumeric_id": "TH_CTRL_LOO+T_IN",
    "id": 108,
    "location": "left",
    "nameDE": "Eintrittstemperatur",
    "nameEN": "Inlet temperature",
    "pin_attributes": [
      {
        "id": 3431,
        "key": "L1_analog_digital",
        "probability": 1,
        "value": "/analog"
      },
      {
        "id": 3432,
        "key": "L2_virtual",
        "probability": 1,
        "value": "/physical"
      },
      {
        "id": 3433,
        "key": "L3_direction",
        "probability": 1,
        "value": "/input"
      },
      {
        "id": 3735,
        "key": "L4_type",
        "probability": 0.7,
        "value": "/temperature/liquid/warm/input flow"
      },
      {
        "id": 3736,
        "key": "L4_type",
        "probability": 0.3,
        "value": "/temperature/liquid/hot/input flow"
      },
      {
        "id": 3737,
        "key": "L5_unit",
        "probability": 0.9,
        "value": "/temperature/Celsius"
      },
      {
        "id": 3738,
        "key": "L5_unit",
        "probability": 0.075,
        "value": "/temperature/Fahrenheit"
      },
      {
        "id": 3739,
        "key": "L5_unit",
        "probability": 0.025,
        "value": "/temperature/Kelvin"
      }
    ]
  },

  ...

  {
    "alphanumeric_id": "TH_CTRL_LOO+T_OUT",
    "id": 110,
    "location": "right",
    "nameDE": "Austrittstemperatur",
    "nameEN": "Outlet temperature",
    "pin_attributes": [
      {
        "id": 3431,
        "key": "L1_analog_digital",
        "probability": 1,
        "value": "/analog"
      },
      {
        "id": 3432,
        "key": "L2_virtual",
        "probability": 1,
        "value": "/physical"
      },
      {
        "id": 3433,
        "key": "L3_direction",
        "probability": 1,
        "value": "/input"
      },
      {
        "id": 3746,
        "key": "L4_type",
        "probability": 0.7,
        "value": "/temperature/liquid/warm/return flow"
      },
      {
        "id": 3747,
        "key": "L4_type",
        "probability": 0.3,
        "value": "/temperature/liquid/hot/return flow"
      },
      {
        "id": 3748,
        "key": "L5_unit",
        "probability": 0.9,
        "value": "/temperature/Celsius"
      },
      {
        "id": 3749,
        "key": "L5_unit",
        "probability": 0.075,
        "value": "/temperature/Fahrenheit"
      },
      {
        "id": 3750,
        "key": "L5_unit",
        "probability": 0.025,
        "value": "/temperature/Kelvin"
      }
    ]
  },

  ...

  {
    "alphanumeric_id": "TH_CTRL_LOO+MSG_ALARM",
    "id": 157,
    "location": "bottom",
    "nameDE": "Alarmmeldung",
    "nameEN": "Alarm message",
    "pin_attributes": [
      {
        "id": 3439,
        "key": "L1_analog_digital",
        "probability": 1,
        "value": "/digital"
      },
      {
        "id": 3440,
        "key": "L2_virtual",
        "probability": 1,
        "value": "/virtual"
      },
      {
        "id": 3441,
        "key": "L3_direction",
        "probability": 1,
        "value": "/output"
      },
      {
        "id": 3455,
        "key": "L4_type",
        "probability": 1,
        "value": "/message/alarm"
      },
      {
        "id": 3443,
        "key": "L5_unit",
        "probability": 1,
        "value": "/scalar/generic"
      }
    ]
  }
]

In addition to the pins, the component defines 10 placeholders for additional attributes. While pins are used to attach real time series data to a component, attributes are used to hold additional meta-data such as regional holidays, timezones, schedules etc.

[
  {
    "alphanumeric_id": "TH_CTRL_LOO+VAL_TYP",
    "id": 42,
    "key": "TH_CTRL_LOO+VAL_TYP",
    "nameDE": "Ventiltyp",
    "nameEN": "Valve type",
    "value_type": "string"
  },
  {
    "alphanumeric_id": "TH_CTRL_LOO+VAL_THR",
    "id": 43,
    "key": "TH_CTRL_LOO+VAL_THR",
    "nameDE": "Ventilschwelle",
    "nameEN": "Valve threshold",
    "value_type": "json"
  },
  {
    "alphanumeric_id": "TH_CTRL_LOO+CUS_DAY_SHD",
    "id": 60,
    "key": "TH_CTRL_LOO+CUS_DAY_SHD",
    "nameDE": "Benutzerdefinierte Tagespläne",
    "nameEN": "Custom day schedules",
    "value_type": "json"
  },

  ...

  {
    "alphanumeric_id": "TH_CTRL_LOO+T_OUT_SP_DEV_TOL",
    "id": 44,
    "key": "TH_CTRL_LOO+T_OUT_SP_DEV_TOL",
    "nameDE": "Sollwertabweichungstoleranz der Austrittstemperatur",
    "nameEN": "Outlet temperature setpoint deviation tolerance",
    "value_type": "float"
  },
  {
    "alphanumeric_id": "TH_CTRL_LOO+SHDO_FLX",
    "id": 66,
    "key": "TH_CTRL_LOO+SHDO_FLX",
    "nameDE": "Abschaltflexibilität",
    "nameEN": "Shutdown flexibility",
    "value_type": "float"
  }
]

Mapped components

Filling the pin placeholders of an abstract component with datapoints from an actual project creates a mapped component from an abstract one. While the initial mapping process is usually carried out by aedifion, the mapped components can be viewed, modified, and deleted once added through the GET/PUT/DELETE /v2/project/{project_id}/componentInProject/{componentinproject_id} endpoints.

You may even create your own mapped components using the following endpoints

  • Use POST /v2/project/{project_id}/componentInProject to instantiate an abstract component into your project.
  • POST/PUT/DELETE /v2/project/{project_id}/componentInProject/pin/datapoint allows you to map datapoints to the pins of your new component instance.
  • POST/PUT/DELETE /v2/project/{project_id}/componentInProject/attributeallows you to fill the attribute placeholders for your component with the desired info.

A detailed walk-through for these endpoints is omitted here for the sake of brevity.

Let's list the already available mapped components using the GET /v2/project/{project_id}/componentsInProject endpoint.

r = requests.get(f"{api_url}/v2/project/1/componentsInProject", 
                 auth=auth_john)
print(r.text)
curl "https://api.aedifion.io/v2/project/1/componentsInProject" 
    -X GET
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Project tag, then the GET /v2/project/{project_id}/componentsInProject endpoint (blue).
  4. Provide the project_id.
  5. Click "Try it out!".
  6. Inspect the response body and code.

The response contains a list of mapped components each with the project ID, a unique numeric ID, and an English name, as well as the ID of the abstract component from which it was instantiated.

{
  "items": [
    {
      "component_id": 17,
      "id": 196,
      "nameEN": "AlarmStateAnalysis_always off",
      "project_id": 12
    },
    {
      "component_id": 21,
      "id": 412,
      "nameEN": "ControlLoopOscillationAnalysis_TCL_green",
      "project_id": 12
    },
    {
      "component_id": 20,
      "id": 190,
      "nameEN": "DewPointAlertAnalysis_temp_and_hum_range_green",
      "project_id": 12
    },

  ...

}

Among others, we find mapped components for thermal control loops (a virtual component which can represent a variety of physical components), a fan, and a room.

Mapped pins and attributes

Using "id": 221 of a mapped weather station component, we can query the details of the component using the GET /v2/project/{project_id}/componentInProject/{componentinproject_id} endpoint. The answer, among other information, contains the mapped datapoints and filled-in attributes. In this example, we have mapped the outside air temperature, the outside air relative humidity, and filled in geo-position as attributes. Note that the answer model also contains the definition of the base component from which this mapped component was instantiated.

{
  "attributes": [
    {
      "alphanumeric_id": "WST+LON",
      "id": 118,
      "key": "WST+LON",
      "value": "9.8576663"
    },
    {
      "alphanumeric_id": "WST+LAT",
      "id": 119,
      "key": "WST+LAT",
      "value": "53.5706442"
    }
  ],
  "component": {
    "alphanumeric_id": "WST",
    "id": 22,
    "nameDE": "Wetterstation",
    "nameEN": "Weather station"
  },
  "display_name": "WeatherStationAnalysis_temperature_and_humidity_green | Weather station",
  "id": 221,
  "nameEN": "WeatherStationAnalysis_temperature_and_humidity_green",
  "pins": [
    {
      "alphanumeric_id": "WST+T_AIR_ODA",
      "dataPointID": "Outside_Temperature_Elbe",
      "id": 121,
      "location": "right",
      "nameDE": "Temperatur",
      "nameEN": "Temperature",
      "pin_attributes": [
        {
          "id": 3431,
          "key": "L1_analog_digital",
          "probability": 1,
          "value": "/analog"
        },
        {
          "id": 3432,
          "key": "L2_virtual",
          "probability": 1,
          "value": "/physical"
        },
        {
          "id": 3433,
          "key": "L3_direction",
          "probability": 1,
          "value": "/input"
        },
        {
          "id": 3560,
          "key": "L4_type",
          "probability": 1,
          "value": "/temperature/gaseous/outdoor"
        },
        {
          "id": 3757,
          "key": "L5_unit",
          "probability": 0.9,
          "value": "/temperature/Celsius"
        },
        {
          "id": 3758,
          "key": "L5_unit",
          "probability": 0.075,
          "value": "/temperature/Fahrenheit"
        },
        {
          "id": 3759,
          "key": "L5_unit",
          "probability": 0.025,
          "value": "/temperature/Kelvin"
        }
      ]
    },
    {
      "alphanumeric_id": "WST+HUM_REL_AIR_ODA",
      "dataPointID": "Outside_Relative_Humidity_Elbe",
      "id": 188,
      "location": "left",
      "nameDE": "Relative Feuchte",
      "nameEN": "Relative humidity",
      "pin_attributes": [
        {
          "id": 3431,
          "key": "L1_analog_digital",
          "probability": 1,
          "value": "/analog"
        },
        {
          "id": 3432,
          "key": "L2_virtual",
          "probability": 1,
          "value": "/physical"
        },
        {
          "id": 3433,
          "key": "L3_direction",
          "probability": 1,
          "value": "/input"
        },
        {
          "id": 3579,
          "key": "L4_type",
          "probability": 1,
          "value": "/relative humidity"
        },
        {
          "id": 3580,
          "key": "L5_unit",
          "probability": 1,
          "value": "/scalar/percent"
        }
      ]
    }
  ],
  "project_id": 12,
  "tags": []
}

Analysis functions

We have explored the available components and seen how they came to life by mapping them. Mapped components are useful for a lot of use cases beyond analytics, e.g., creating pre-defined monitoring dashboards. Here, however, we focus on how we can analyze the performance of these components.

We detail all available analysis functions in the engineering part of this docs and just list the most basic information about them using the API endpoint GET /v2/analytics/functions. This endpoint requires a single query parameter component which should be the English name of the component for which you want to list available analyses. In the next example, we query all analysis functions available for weather stations (alphanumeric ID: WST)

r = requests.get(f"{api_url}/v2/analytics/functions",
                 auth=auth_john,
                 params={'component_alphanumeric_id': 'WST'})
print(r.text)
curl 'https://api.aedifion.io/v2/analytics/functions'
    -X GET
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd
    -d {'component_alphanumeric_id': 'WST'}
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Analytics tag, then the GET /v2/analytics/functions endpoint (blue).
  4. Provide the component.
  5. Click "Try it out!".
  6. Inspect the response body and code.

The answer tells us that there is a total of two analysis functions ready to be run on a mapped weather station component. Each analysis function has a unique alphanumeric ID, a numeric ID, an English name, and a German name.

[
  {
    "alphanumeric_id": "weather_station_analysis",
    "id": 12,
    "nameDE": "Wetterstationsanalyse",
    "nameEN": "Weather Station Analysis"
  },
  {
    "alphanumeric_id": "sensor_outage_analysis",
    "id": 16,
    "nameDE": "Sensorausfallanalyse",
    "nameEN": "Sensor Outage Analysis"
  }
]

Analysis instances

An analysis instance essentially links an analysis function to a component which is to be analyzed. Only one instance is allowed per combination of analysis function and component.

Post instance

To apply an analysis function to a mapped component, we need to create an analysis instance using the POST /v2/analytics/instance endpoint.

r = requests.post(f"{api_url}/v2/analytics/instance",
                  auth=auth_john,
                  params={"project_id": 12},
                  json={
                      "analysisfunction_id": 17,
                      "componentinproject_id": 203,
                      "description": "This is a demo instance.",
                      "enabled": True,
                      "name": "Demo"}
                  )
print(r.status_code, r.json())
curl 'https://api.aedifion.io/v2/analytics/instance?project_id=12'
    -X POST
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd
    -d {
        "analysisfunction_id": 17,
        "componentinproject_id": 203,
        "description": "This is a demo instance.",
        "enabled": True,
        "name": "Demo"
        }
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Analytics tag, then the POST /v2/analytics/instance endpoint (green).
  4. Provide the project_id.
  5. Create the instance_config by adding: analysisfunction_id, componentinproject_id, description, enabled and name keys. A template for generating the instance_config can be found under "Example Value".
  6. Click "Try it out!".
  7. Inspect the response body and code.

If the combination of analysis function and component already exists as an instance, the following error is returned:

{
    'error': "Analysis instance for component in project id: '203' and analysis function id: '17' already exists.", 
    'operation': '', 
    'success': False
}

Enabled key

When creating an instance, either via the Swagger UI or a script, an "enabled" key can be set. This key determines that the analysis function will be automatically executed on the component every week (from Monday to Monday) in addition to other analytics runs the user may implement. If the key is set to "false", the user can manually create analytics runs for customized analysis periods.

An existing analysis instance with ID = 753 for the above queried thermal control loop component using the GET /v2/analytics/instance/{instance_id} endpoint. This endpoint requires the project_id as a query parameter and the instance_id as path parameter.

Note that you can also use the GET /v2/analytics/instances endpoint to query a list of all analysis instances within a project.

r = requests.get(f"{api_url}/v2/analytics/instance/753",
                 auth=auth_john,
                 params={'project_id': 12})
print(r.text)
curl 'https://api.aedifion.io/v2/analytics/instance/753'
    -X GET
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd
    -d {'project_id': 12}
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Analytics tag, then the GET /v2/analytics/instances endpoint (blue).
  4. Provide the project_id.
  5. Click "Try it out!".
  6. Inspect the response body and code.

The answer contains the configuration of the queried analysis instance. We can see that it references a single analysis function with ID = 753. The synchronized operation analysis with function with the function ID 11 (alphanumeric ID "synchronized_operation_analysis"), is linked to the thermal control loop (componentinproject_id: 434). See analysis functions for more information. The English name and the description are automatically generated when instances are created in the front-end.

{
  "config": {
    "analysisfunction_id": 11,
    "componentinproject_id": 434,
    "description": "frontend-generated",
    "enabled": true,
    "name": "Synchronized Operation Analysis for thermal_control_loop"
  },
  "id": 753,
  "project_id": 12
}

Running an analysis

To run the analysis instance ID = 318, we would invoke the POST /v2/analytics/instance/{instance_id}/run endpoint and provide a time range using the start and end parameters for which we want to run the analysis. When the enabled tag is set to "true", the instance is automatically run weekly. For the sake of brevity, we omit a full example here and continue with examining already computed results.

Analysis results

There are two ways of listing analysis results, per component or per instance.

Listing results per component

In a usual scenario, we have configured multiple analysis instances for one mapped component where each instance analyzes different aspects of the component's operation. In most cases, we are interested in the performance of the component as a whole, i.e., we want to list results grouped by components. The GET /v2/analytics/componentsInProject endpoint returns a list of the latest result for each analysis instance grouped by component (components without analysis instances and analysis instances without results are left out). Additionally, the GET /v2/analytics/componentInProject/{componentinproject_id}/results returns detailed information of a component containing analysis results and a list of result IDs associated with it.

Listing results per instance

In the previous section, we queried results grouped by component. However, we only got the most recent results. If we want to take a deeper look and also investigate past results, we need to use the GET /v2/analytics/instance/{instance_id}/results endpoint which lists all available results for a specific analysis instance (as opposed to the previous GET /v2/analytics/results endpoint which listed only the most recent result per instance, but for all instances, and grouped by component).

In the next example, we list all available results for analysis instance ID = 318.

r = requests.get(f"{api_url}/v2/analytics/instance/318/results",
                 auth=auth_john,
                 params={'project_id': 1})
print(r.text)
curl 'https://api.aedifion.io/v2/analytics/instance/318/results'
    -X GET
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd
    -d {'project_id': 1}
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Analytics tag, then the GET /v2/analytics/results endpoint (blue).
  4. Provide the project_id.
  5. Click "Try it out!".
  6. Inspect the response body and code.

The response contains a list of results. In this example, two results are shown for the same five day period in 2018 and 2019. For each result, we get a unique reference, the time range over which the analysis was conducted, and a status indicating success or failure.

[
  {
    "input_parameters": {
      "end": "2018-10-15 00:00:00+00:00",
      "start": "2018-10-10 00:00:00+00:00"
    },
    "result_id": "d927629a-a144-4f8b-b7c2-b0b256585371",
    "status": "Success."
  },
  {
    "input_parameters": {
      "end": "2019-10-15 00:00:00+00:00",
      "start": "2019-10-10 00:00:00+00:00"
    },
    "result_id": "dfd3a3e7-c17f-4ac9-9a8b-f93c2f56cee4",
    "status": "Success."
  }
]

Getting result details

To get the details of a single result, we supply the unique result_id to the GET /v2/analytics/instance/{instance_id}/result/{result_id} endpoint.

r = requests.get(f"{api_url}/v2/analytics/instance/318/result/"\
                 "dfd3a3e7-c17f-4ac9-9a8b-f93c2f56cee4",
                 auth=auth_john,
                 params={'project_id': 1, 'result_language': 'en'})
print(r.text)
curl 'https://api.aedifion.io/v2/analytics/instance/318/result/dfd3a3e7-c17f-4ac9-9a8b-f93c2f56cee4'
    -X GET
    -u john.doe@aedifion.com:s3cr3tp4ssw0rd
    -d {'project_id': 1, 'result_language': 'en'}
  1. Point your browser to https://api.aedifion.io/ui/.
  2. Click "Authorize" on the upper right and provide your login.
  3. From the main tags (Meta, Company, ...) select the Analytics tag, then the GET /v2/analytics/instance/{instance_id}/result/{result_id} endpoint (blue).
  4. Provide the project_id.
  5. Click "Try it out!".
  6. Inspect the response body and code.

The response contains a lot of information, the most important parts being:

  • the core KPIs that were computed,
  • an interpretation of what these KPIs mean from an engineering perspective,
  • a list of recommendations that should be taken to improve the operation of the analyzed component,
  • a high level signal color (red, yellow, green) summarizing how well the component operated w.r.t. the specified time range and analysis function.
{
  "end": "2019-10-15 00:00:00+00:00",
  "function_name": "temperature_spread_analysis",
  "info": [],
  "instance_id": 318,
  "interpretation": "Increased temperature spread between \"outlet temperature\" and \"inlet temperature recirculation\".",
  "kpi": [
    {
      "name": "temperature spread.average",
      "unit": "°C",
      "value": 14.9
    },
    {
      "name": "temperature spread.minimum",
      "unit": "°C",
      "value": -0.104
    },
    {
      "name": "temperature spread.maximum",
      "unit": "°C",
      "value": 23.4
    }
  ],
  "project_id": 1,
  "recommendation": [
    "Increase in volume flows improves heat supply."
  ],
  "signal_color": "yellow",
  "start": "2019-10-10 00:00:00+00:00",
  "status": "Success."
}

Last update: 2020-12-02