Favorites, tagging, renaming

This article deals with managing favorites, renamings, and tags for datapoints.

Overview

This article deals with creating favorites, renamings, and tags on datapoints as well as modifying and removing them. We start by adding, querying, and removing favorite datapoints. We then cover the concept of datapointkeys, and show how datapoints can be assigned alternate names (renamings). Finally, we cover creating tags, assigning them to datapoints, modifying them and their association with a datapoint, and ultimately removing associations with a datapoint or removing tags completely.

We provide concrete examples on how to use the aedifion HTTP API to create, inspect, modify and delete favorites, renamings, tags and tag assignments to datapoints.

Preliminaries

The examples provided in this article partly build on each other. For the sake of brevity, boiler plate code such as imports or variable definitions is 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 datapoints.

  • Optionally, a working installation of Python or Curl.

Favorites

Favorites are a way of flagging datapoints that you frequently view. They are, e.g., used in the frontend to sort the datapoint selector list where they are marked by a star ⭐️. Favorites are scoped to the user, i.e., each user can have different favorites and is not able to see other users' favorites.

Adding a favorite

You flag a datapoint as a favorite using the POST /v2/datapoint/favorite endpoint which takes the following parameters:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

query

yes

The numeric id of the project to which the datapoint belongs.

1

dataPointID

string

query

yes

The alphanumeric identifier of the datapoint to flag as favorite.

bacnet100-4120-CO2

Note that all parameters are query parameters, i.e., they're added in url-encoded form to the query part of the requested URL (the part following the domain and path separated by a question mark). If you are not aware of the project_id you are authenticated for, check out the Viewing company details tutorial.

Python
Curl
Swagger UI
Python
import requests
api_url = "https://api.aedifion.io"
auth = ("john.doe@aedifion.com", "mys3cr3tp4ss0wrd")
project_id = 1
query_params = {'project_id': project_id, 'dataPointID': 'bacnet100-4120-CO2'}
r = requests.post(f"{api_url}/v2/datapoint/favorite",
auth=auth,
params=query_params)
print(r.status_code, r.json())

Please note the configuration, how HTTP requests are built and authenticated, and how different parts of the response are printed and parsed since, for the sake of brevity, we will not repeat this configuration and code in the following examples.

Curl
curl 'https://api.aedifion.io/v2/datapoint/favorite?project_id=1&dataPointID=bacnet100-4120-CO2'
-X POST
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Curl on windows cmd:

The windows cmd handles quotes and special characters differently from other systems! Use double quotes instead of single quotes to delimit a parameter.

Swagger UI
  1. Point your browser to https://api.aedifion.io/ui/.

  2. Click Authorize on the upper right and provide your login (if you haven't already).

  3. From the main tags (Meta, Company, ...) select the Datapoint tag, then the POST /v2/datapoint/favorite endpoint (green).

  4. Provide both the project_id and dataPointID to identify the datapoint that you want to flag as a favorite.

  5. Click "Try it out!".

  6. Inspect the response body and code.

Posting a favorite creates a relation between you (your user account) and a datapoint. On success, this relation (user, datapoint) is returned in the resource field of the answer.

{
"operation": "create",
"resource": {
"datapoint": {
"dataPointID": "bacnet100-4120-CO2",
"hash_id": "Jw0EdgdG",
"id": 121,
"project_id": 1
},
"user": {
"company_id": 1,
"email": "john.doe@aedifion.com",
"firstName": "John",
"id": 1,
"lastName": "Doe"
}
},
"success": true
}

Let's shoot a few more requests and flag the following as favorites, too:

  • CO2_within_your_office

  • TEMP_within_your_office

You can only flag datapoints as favorites that exist in your project. If you pass a non-existing dataPointID, you will get the following error:

{
"error":"Datapoint does not exist in project: 'does_not_exist'",
"operation":"create",
"success":false
}

Querying favorites

What use are favorites when you cannot quickly access them? That's what the GET /v2/project/{project_id}/datapoints/favorites endpoint is there for. It takes the project_id as single parameter and returns all of the logged-in user's favorites.

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

query

yes

The numeric id of the project from which to retrieve favorites.

1

Python
Curl
Swagger UI
Python
r = requests.get(f"{api_url}/v2/project/{project_id}/datapoints/favorites",
auth=auth)
print(r.status_code, r.json())
Curl
curl 'https://api.aedifion.io/v2/project/1/datapoints/favorites'
-X GET
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd
Swagger UI
  1. Point your browser to https://api.aedifion.io/ui/.

  2. Click Authorize on the upper right and provide your login (if you haven't already).

  3. From the main tags (Meta, Company, ...) select the Project tag, then the GET /v2/project/{project_id}/datapoints/favorites endpoint (blue).

  4. Provide the project_id of the project for which you want to retrieve favorites.

  5. Click "Try it out!".

  6. Inspect the response body and code.

The response is a list of all your favorite datapoints in the specified project.

[
...,
"bacnet100-4120-CO2",
"CO2_within_your_office",
"datapoint_within_your_office",
"TEMP_within_your_office",
...
]

Deleting a favorite

Maybe that datapoint_within_your_office is not that important, after all. Removing it from the list of your favorites is a simple matter of calling DELETE /v2/datapoint/favorite with the usual parameters:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

query

yes

The numeric id of the project to which the datapoint belongs.

1

dataPointID

string

query

yes

The alphanumeric identifier of the datapoint to remove as favorite.

datapoint_

within_

your_office

Python
Curl
Swagger UI
Python
query_params = {'project_id': project_id, 'dataPointID': 'datapoint_within_your_office'}
r = requests.delete(f"{api_url}/v2/datapoint/favorite",
auth=auth,params=query_params)
print(r.status_code, r.json())
Curl
curl 'https://api.aedifion.io/v2/datapoint/favorite?project_id=1&dataPointID=datapoint_within_your_office'
-X POST
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd
Swagger UI
  1. Point your browser to https://api.aedifion.io/ui/.

  2. Click Authorize on the upper right and provide your login (if you haven't already).

  3. From the main tags (Meta, Company, ...) select the Datapoint tag, then the DELETE /v2/datapoint/favorite endpoint (red).

  4. Provide both the project_id and dataPointID to identify the datapoint that you want to remove from your favorites.

  5. Click "Try it out!".

  6. Inspect the response body and code.

The answer confirms the deletion of the favorite and returns the deleted (user, datapoint) relation similar to the creation of a favorite.

{
"operation": "delete",
"resource": {
"datapoint": {
"dataPointID": "datapoint_within_your_office",
"hash_id": "Jw0EdgdG",
"id": 121,
"project_id": 1
},
"user": {
"company_id": 1,
"email": "john.doe@aedifion.com",
"firstName": "John",
"id": 1,
"lastName": "Doe"
}
},
"success": true
}

Creating and deleting favorites is idempotent, i.e., calling POST /v2/datapoint/favorite multiple times has the same effect as calling it once (same for DELETE).

Renamings

A datapoint identifier (dataPointID) is obtained directly and automatically from the component from which the datapoint is read, e.g., from a BACnet device. Thus, the dataPointIDs that are displayed as a datapoint's default name are not necessarily nice to read or even correct.

Renamings provide a way to assign a different name (or even multiple different names) to a datapoint. A renaming always belongs to a datapointkey which bundles related renamings of multiple datapoints. This allows, e.g., to add a translation of datapoint names into different languages (the datapointkey would be the language) or to add standardized datapoint names (the datapointkey would be the name of the standard such as BUDO).

In the following, we demonstrate the renaming flow by the example of translating some datapoints' names to german.

Adding datapointkeys

Before we can rename any datapoints, we need to create a datapointkey that bundles the datapoint renamings. A new datapointkey is created through POST /v2/project/{project_id}/datapointkey.

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

path

yes

The numeric id of the project for which to add a datapointkey

1

name

string

body

(JSON)

yes

The name of the new datapointkey (must be unique within the project).

german

description

string

body

(JSON)

no

A short textual description for the datapointkey that helps understanding what this datapointkey is about.

Translation into german language.

To create the new datapointkey, we pass the project_id in the path of the request and the details of the new datapointkey in the request's body encoded as a JSON object.

Python
Curl
Swagger UI
Python
new_key = {"name": "german",
"description": "Translation into german language."}
r = requests.post(f"{api_url}/v2/project/{project_id}/datapointkey",
auth=auth,
json=new_key)
print(r.status_code, r.json())
Curl
curl https://api.aedifion.io/v2/project/1/datapointkey
-X POST
-H 'Content-Type: application/json'
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd
-d '{
"description": "Translation into german language.",
"name": "german"
}'
Swagger UI
  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 POST /v2/project/{project_id}/datapointkey endpoint (green).

  4. Copy-paste then edit the example value and provide the project_id.

  5. Click "Try it out!".

  6. Inspect the response body and code.

The response confirms the creation of the new datapointkey. Note down the id as we will need it later.

{
"operation": "create",
"resource": {
"decription": "Translation into german language.",
"id": 19,
"name": "german",
"project_id": 1
},
"success": true
}

Now that we have created a new datapointkey, we can go ahead and rename datapoints w.r.t. this datapointkey.

Adding renamings

A renaming of a datapoint is added through the POST /v2/datapoint/renaming endpoint which requires the following parameters:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

query

yes

The numeric id of the project for which to rename datapoint.

1

dataPointID

string

query

yes

The alphanumeric identifier of the datapoint to rename.

datapoint_ within_ your_office

datapointkey_id

integer

body

(JSON)

yes

The numeric id of the datapointkey which to associate the renaming to.

19

renaming

string

body

(JSON)

yes

The new name for the datapoint w.r.t. the chosen datapointkey.

datenpunkt_in _deinem_büro

Python
Curl
Swagger UI
Python
query_params = {"project_id": project_id,
"dataPointID": "datapoint_within_your_office"}
renaming = {"datapointkey_id": 19,
"renaming": "datenpunkt_in_deinem_büro"}
r = requests.post(f"{api_url}/v2/datapoint/renaming",
auth=auth,
params=query_params,
json=renaming)
print(r.status_code, r.json())
Curl
curl 'https://api.aedifion.io/v2/datapoint/renaming?project_id=1&dataPointID=datapoint_within_your_office'
-X POST
-H 'Content-Type: application/json'
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd
-d '{
"datapointkey_id": 19,
"renaming": "datenpunkt_in_deinem_büro"
}'
Swagger UI
  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 Datapoint tag, then the POST /v2/datapoint/renaming endpoint (green).

  4. Copy-paste then edit the example value and provide the project_id and the dataPointID.

  5. Click "Try it out!".

  6. Inspect the response body and code.

On success, the response confirms the creation of the renaming.

{
"operation": "create",
"resource": {
"datapointkey_id": 19,
"id": 16,
"renaming": "datenpunkt_in_deinem_büro"
},
"success": true
}

If the datapoint already has a renaming w.r.t. this datapointkey an error is returned:

{
"error": "Renaming 16 already renames datapoint 121 for datapointkey 19.",
"operation": "create",
"success": false
}

In the latter case, modifying the existing renaming may be necessary.

Modifying renamings

An existing renaming can be changed using the PUT /v2/datapoint/renaming/{renaming_id} endpoint.

Parameter

Datatype

Type

Required

Description

Example

renaming_id

integer

path

yes

The numeric id of the renaming to modify.

16

renaming

string

body

(JSON)

yes

The new renaming.

Datenpunkt in deinem Büro

We provide the renaming_id in the path and the updated name in the request's body.

Python
Curl
Swagger UI
Python
update = {"renaming": "Datenpunkt in deinem Büro"}
renaming_id = 16
r = requests.put(f"{api_url}/v2/datapoint/renaming/{renaming_id}",
auth=auth,
json=update)
print(r.status_code, r.json())
Curl
curl https://api.aedifion.io/datapoint/renaming/16
-X PUT
-H 'Content-Type: application/json'
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd
-d '{"renaming":"Datenpunkt in deinem Büro"}'
Swagger UI
  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 Datapoint tag, then the PUT /v2/datapoint/renaming/{renaming_id} endpoint (orange).

  4. Copy-paste then edit the example value and provide the renaming_id.

  5. Click "Try it out!".

  6. Inspect the response body and code.

On success, the answer returns the new renaming.

{
"operation": "update",
"resource": {
"datapointkey_id": 19,
"id": 16,
"renaming": "Datenpunkt in deinem Büro"
},
"success": true
}

Go ahead and also rename CO2_in_your_office to CO2 in deinem Büro.

Querying datapointkeys and renamings

Calling GET /v2/project/{project_id}/datapointkeys provides a list of all datapointkeys in the given project.

Python
Curl
Swagger UI
Python
r = requests.get(f"{api_url}/v2/project/{project_id}/datapointkeys",
auth=auth)
print(r.status_code, r.json())
Curl
curl 'https://api.aedifion.io/v2/project/1/datapointkeys'
-X GET
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd
Swagger UI
  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}/datapointkeys endpoint (blue).

  4. Provide the project_id.

  5. Click "Try it out!".

  6. Inspect the response body and code.

Verify that your newly created datapointkey is among this list.

[
...,
{
"decription": "Translation into german language.",
"id": 19,
"name": "german",
"project_id": 4
},
...
]

Calling GET /v2/project/{project_id}/datapoints/renamings with datapointkey_id=19 as a query parameter then returns all available german translations, i.e., renamings under datapointkey 19.

Python
Curl
Swagger UI
Python
r = requests.get(f"{api_url}/v2/project/{project_id}/datapoints/renamings",
auth=auth,
params={'datapointkey_id':19})
print(r.status_code, r.json())
Curl
curl 'https://api.aedifion.io/v2/project/1/datapoints/renamings?datapointkey_id=19'
-X GET
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd
Swagger UI
  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}/datapoints/renamings endpoint (blue).

  4. Provide the project_id and datapointkey_id.

  5. Click "Try it out!".

  6. Inspect the response body and code.

Verify that the created german translations of the datapoint_within_your_office and CO2_in_your_office datapoints are within the returned list.

[
...,
{
"dataPointID": "datapoint_within_your_office",
"renamings": [
{
"datapointkey_id": 19,
"id": 16,
"renaming": "Datenpunkt in deinem Büro"
}
]
},
{
"dataPointID": "CO2_within_your_office",
"renamings": [
{
"datapointkey_id": 19,
"id": 17,
"renaming": "CO2 in deinem Büro"
}
]
},
...
]

Deleting renamings

Calling DELETE /v2/datapoint/renaming/{renaming_id} deletes a renaming. The call only requires the id of the renaming to delete.

Python
Curl
Swagger UI
Python
r = requests.delete(f"{api_url}/v2/datapoint/renaming/16",
auth=auth)
print(r.status_code, r.json())
Curl
curl 'https://api.aedifion.io/v2/datapoint/renaming/16'
-X DELETE
-u john.doe@aedifion.com:mys3cre3tp4ssw0rd
Swagger UI
  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 Datapoint tag, then the DELETE /v2/datapoint/renaming/{renaming_id} endpoint (red).

  4. Provide the renaming_id.

  5. Click "Try it out!".

  6. Inspect the response body and code.

The response returns the deleted renaming:

{
"operation": "delete",
"resource": {
"datapointkey_id": 19,
"id": 16,
"renaming": "Datenpunkt in deinem Büro"
},
"success": true
}

Removing renamings one-by-one is tedious. If all renamings for a given datapointkey should be deleted, you can simply delete the datapointkey which will automatically delete all associated renamings with it.

Deleting datapointkeys

Calling DELETE /v2/project/{project_id}/datapointkey/{datapointkey_id} deletes a datapointkey together with all associated renamings.

Python
Curl
Swagger UI
Python
r = requests.delete(f"{api_url}/v2/project/1/datapointkey/19",
auth=auth)
print(r.status_code, r.json())
Curl
curl 'https://api.aedifion.io/v2/project/1/datapointkey/19'
-X DELETE
-u john.doe@aedifion.com:mys3cr3tp4ssw0rd
Swagger UI
  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 DELETE /v2/project/{project_id}/datapointkey/{datapointkey_id} endpoint (red).

  4. Provide the project_id and datapointkey_id.

  5. Click "Try it out!".

  6. Inspect the response body and code.

The response returns the deleted datapointkey:

{
"operation": "delete",
"resource": {
"decription": "Translation into german language.",
"id": 19,
"name": "german",
"project_id": 1
},
"success": true
}

Deleting a datapoinkey also irreversibly deletes all associated renamings.

Tags

Tags are a way to annotate your datapoints. aedifion's tags are labels consisting of a key-value pair. For example, if you have a set of datapoints located inside your office, you can tag them with the key-value pair ('location', 'Office A113'). Subsequently, the tagged datapoints can be easily accessed by the API. Tags are strictly project-scoped, i.e, they are shared within a project and can be assigned to multiple datapoints of that project but are never shared across different projects.

aedifion also provides automatically created tags, e.g., datapoint properties read from BACnet or machine learning results.

We will cover all relevant API endpoints by the example of annotating datapoints with the office location.

Types of tags

Tags are inherently only a key-value pair with an additional unique numeric id for easy access. The following tag represents a location information.

{
"id": 42,
"key": "location",
"value": "Office A113"
}

A tag can be assigned to multiple datapoints. All tag assignments have a sources. Currently, sources are one of the following but may be extended in future:

  • user: The tag has been assigned by a user. Any tag assigned through the API is designated a user generated tag assignment.

  • ai: The tag has been assigned by an artificial intelligence (ai).

  • bacnet: The tag assignment has been derived from BACnet meta data.

In the following, we will often use the terms tag and tag assignment synonymously since the difference rather lies in the implementation than in the concept.

User generated tag
BACnet tag
Classification tag
User generated tag

The following example shows a tag assigned to a datapoint by a user ("source"="user"). Besides the known properties id, key, and value additional properties are present. The property confirmed is not shown since the assignment has neither been confirmed or rejected. The property protected indicates, that this assigned tag can be changed.

{
"id": 42,
"key": "location",
"protected": false,
"source": "user",
"value": "Office A113"
}
BACnet tag

The following example shows a tag that has been automatically created and assigned to a datapoint by a BACnet logger ("source"="bacnet"). Besides the known properties id, key, and value additional properties are present. The property confirmed indicates that the assigned tag has been verified by a user. The property protected notes, that this assigned tag cannot be changed (since it is information read from BACnet).

{
"confirmed": true,
"id": 42,
"key": "description",
"protected": true,
"source": "bacnet",
"value": "Temperature sensor in Room 1.113"
}
Classification tag

The following example excerpt shows a tag assigned to a datapoint by aedifion's machine learning service ("source"="ai"). Besides the known properties id, key, and value additional properties are present. The property confirmed indicates that the assigned tag has been rejected by a user. The property protected notes, that this assigned tag cannot be changed (since it is provided by the artificial intelligence). Furthermore, a probability is provided from the machine learning system which indicates the confidence of the resulting class.

{
"confirmed": false,
"id": 42,
"key": "class",
"probability": 0.9,
"protected": true,
"source": "ai",
"value": "Temperature"
}

Adding tags

The API allows to create tags as key-value pairs. Subsequently, you can assign this tag to a datapoint. We want to create the tag ('location', 'Office A113') to some of our datapoints. To this end, we use the POST /v2/project/{project_id}/tag which takes the following parameters:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

path

yes

The numeric id of the project for which to create the tag.

1

key

string

body (JSON)

yes

The key of the tag.

location

value

string

body

(JSON)

no

The value of the tag.

Office A113

project_id is a path parameter, i.e., it is entered directly in the requests path while the parameters key and value must be encoded as a valid JSON and sent in the body of the request.

Python
Curl
Swagger UI
Python
import requests
api_url = "https://api.aedifion.io"
john = ("john.doe@aedifion.com", "mys3cr3tp4ss0wrd")
project_id = 1
newtag = {'key': 'location', 'value': 'Office A113'}
r = requests.post(api_url + f"/v2/project/{project_id}/tag",
auth=john,
json=newtag)
print(r.status_code, r.json())
Curl
  1. Copy-paste the JSON into a file, e.g., named newtag.json.

    newtag.json
    {
    "key": "location",
    "value": "Office A113"
    }
  2. Open a commandline.

  3. Execute the following command.

    curl https://api.aedifion.io/v2/project/1/tag
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -d @newtag.json
    -H "Content-Type: application/json"
Swagger UI
  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 POST /v2/project/{project_id}/tag endpoint (green).

  4. Copy-paste the above JSON into the value of the tag parameter and fill out the project_id.

  5. Click "Try it out!".

  6. Inspect the response body and code.

We get the following JSON-formatted response from the API which states that the tag has been successfully created as indicated by the return code: 201 (Created).

{
"success": true,
"operation": "create",
"resource": {
"id": 42,
"key": "location",
"value": "Office A113"
}
}

Go ahead and create the same tag, i.e., same key and value, a second time. Note how this will not produce an error but instead return the already existing tag and change return code to 200 (OK).

You can only create a tag with the same key and value pair once. But you can use the tag multiple times.

For now, our newly created tag is not assigned to any datapoint. Let's now assign this tag to an existing datapoint. For this we have to use the POST /v2/datapoint/tag endpoint which requires the following parameters:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

query

yes

The numeric id of the project from which to assign a tag.

1

dataPointID

string

query

yes

The alphanumeric id of the datapoint which to assign a tag to.

datapoint_

within_

your_office

tag_id

integer

query

yes

The numeric id of the tag to assign.

42

Note that all parameters are query parameters, i.e., they're added in url-encoded form to the query part of the requested URL (the part following the domain and path separated by a question mark).

Python
Curl
Swagger UI
Python
import requests
project_id = 1
dataPointID = 'datapoint_within_your_office'
tag_id = 42
r = requests.post(api_url + "/v2/datapoint/tag",
auth=john,
params={'project_id':project_id,
'dataPointID': dataPointID,
'tag_id':tag_id})
print(r.status_code, r.json())
Curl
  1. Open a commandline.

  2. Execute the following command.

    curl 'https://api.aedifion.io/v2/project/1/tag?project_id=1&\
    dataPointID=datapoint_within_your_office&tag_id=42'
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -H "Content-Type: application/json"
Swagger UI
  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 Datapoint tag ,then the POST /v2/datapoint/tag endpoint (green).

  4. Fill out all the neccessary parameters.

  5. Click "Try it out!".

  6. Inspect the response body and code.

We get the following response from the API which indicates a successful assignment of the tag to the datapoint. Since an assignment is a relation between two entities, it returns both entities, the datapoint and the assigned tag, in the resource field. Note that "source": "user" was added automatically.

{
"operation": "create",
"resource": {
"datapoint": {
"dataPointID": "datapoint_within_your_office",
"hash_id": "ABCD1234",
"project_id": 1
},
"tag": {
"id": 42,
"key": "location",
"protected": false,
"source": "user",
"value": "Office A113"
}
},
"success": true
}

Listing tags

Since we just created the tag we knew the required tag_id to assign it to a datapoint. If you want to assign a previously created tag but you do not know the tag_id, you can get an overview of all possible key-value pairs in combination with their IDs (tag_id) by using the GET /v2/project/{project_id}/tags endpoint with the following parameters:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

path

yes

The numeric id of the project from which to assign a tag.

1

key

string

query

no

Optional key to filter the returned tags by their key.

location

For this method we need a GET request. Therefore, we use requests.get.

Python
Curl
Swagger UI
Python
import requests
project_id = 1
r = requests.get(apif"/v2/project/{project_id}/tags",
auth=("email", "password"),
params={'key': 'location'})
print(r.status_code, r.json())
Curl
  1. Open a commandline.

  2. Execute the following command.

    curl 'https://api.aedifion.io/v2/project/1/tags?key=location'
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -H "Content-Type: application/json"
Swagger UI
  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/datapoint/tag endpoint (blue).

  4. Fill out all the neccessary parameters.

  5. Click "Try it out!".

  6. Inspect the response body and code.

Since we provided the optional key parameter only the tags with the key "location" are returned:

[
{
"id": 42,
"key": "location",
"value": "Office A113"
},
{
"id": 43,
"key": "location",
"value": "Office A114"
}
]

Modifying tags

With the Aedifion API you can either modify the tag directly (i.e. the key or the value) or the tag assignment (i.e. the confirmed status). The first method affects all assignments the user has made. This method is conceived e.g. for fixing typos in the tags. The second method is to verify the tag assignment (set the confirmed status).

For example if your company decides to rename the offices (e.g. from A113 to B113), you do not need to recreate all the tags; you can just modify them. To modify the key and/or the value of the tag use the API endpoint PUT /v2/project/{project_id}/tag/{tag_id}. It requires the following parameters:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

path

yes

The numeric id of the project from which to assign a tag.

1

tag_id

integer

path

yes

The numeric id of the tag.

42

key

string

body (JSON)

no

The new key of the tag.

Location

value

string

body (JSON)

no

The new value of the tag.

Office B113

Let us now rename the created tag to the new Office name. We have to provide the project_id, tag_id, and the new value.

Python
Curl
Swagger UI
Python
import requests
project_id = 1
tag_id = 42
r = requests.put(api_url + f"/v2/project/{project_id}/tag/{tag_id}",
auth=john,
json={"value": "Office B113"})
print(r.status_code, r.json())
Curl
  1. Copy-paste the JSON into a file, e.g., named updatetag.json.

    updatetag.json
    {
    "key": "location",
    "value": "Office B113"
    }
  2. Open a commandline.

  3. Execute the following command.

    curl https://api.aedifion.io/v2/project/1/tag/42
    -X PUT
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -d @updatetag.json
    -H "Content-Type: application/json"
Swagger UI
  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 PUT /v2/project/{project_id}/tag/{tag_id} endpoint (yellow).

  4. Copy-paste the above JSON into the value of the tag parameter and fill out the the neccessary parameters.

  5. Click "Try it out!".

  6. Inspect the response body and code.

As a response we either get a 200 or 201 status code. This depends on whether the API edited the tag in-place or had to create a new tag. The latter case might have happened if for example the BACnet logger has assigned the same tag to another datapoint. In this case all user-made assignments are updated to use the new tag_id.

If there are tags assigned by another source or protected tag assignments, a new tag (with a new tag_id) is created and a 201 HTTP response is returned.

200 (in place)
201 (new tag)
200 (in place)
{
"operation": "update",
"resource": {
"id": 42,
"key": "location",
"value": "Office B113"
},
"success": true
}
201 (new tag)
{
"operation": "update",
"resource": {
"id": 43,
"key": "location",
"value": "Office B113"
},
"success": true
}

Modifying tag assignments

You can also modify the tag assignment to a datapoint (here: confirm or reject the assignment). This is especially useful for automatically generated tags (e.g. from BACnet or from machine learning). Modifying these will help find faulty datapoints and improve our machine learning systems. For this we use the endpoint put /v2/datapoint/tag/{tag_id} with the following parameters:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

query

yes

The numeric id of the project from which to assign a tag.

1

tag_id

integer

path

yes

The numeric id of the tag.

42

dataPointID

string

query

yes

The alphanumeric id of the datapoint which to assign a tag to.

datapoint_

within_

your_office

confirmed

string

body (JSON)

yes

The confirmed status of the assignment. Either "true" (correct assignment), "false" (incorrect assignment) or "unconfirmed" (unknown assignment).

"true"

With this method we can now confirm our created tag as an example.

Python
CURL
Swagger UI
Python
import requests
project_id = 1
tag_id = 42
r = requests.put(api_url + f"/v2/datapoint/tag/{tag_id}",
auth=john
params = {
"dataPointID": "datapoint_within_your_office",
"project_id": project_id,
},
json={'confirmed': 'true'})
print(r.status_code, r.json())
CURL
  1. Copy-paste the JSON into a file, e.g., named confirmedtag.json.

    confirmedtag.json
    {
    "confirmed": "true"
    }
  2. Open a commandline.

  3. Execute the following command.

    curl 'https://api.aedifion.io/v2/datapoint/tag/42?
    dataPointID=datapoint_within_your_office&project_id=1'
    -X PUT
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -d @confirmedtag.json
    -H "Content-Type: application/json"
Swagger UI
  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 Datapoint tag ,then the PUT /v2/project/{project_id}/tag/{tag_id} endpoint (yellow).

  4. Copy-paste the above JSON into the value of the tag parameter and fill out the the neccessary parameters.

  5. Click "Try it out!".

  6. Inspect the response body and code.

The response for this API method returns the modified tag associated with this datapoint. If a tag is assigned by multiple sources (e.g. "user" and "bacnet") to this datapoint, all of these assignments are modified. Note, that the "confirmed" parameter is now set to true.

{
"operation": "update",
"resource": [
{
"confirmed": true,
"id": 42,
"key": "location",
"protected": false,
"source": "user",
"value": "B113"
}
],
"success": true
}

Filtering datapoints by tag

You can retrieve all datapoints corresponding to different tags. You must provide a tag key. Optional parameters are the tag value, the assigning source, or the confirmed status. The API call returns a list of all datapoints conforming with all those filters combined with the relevant tags.

This method is intended for fast retrieval of datapoints with tags assigned to it. For example one could get the list of all datapoints with a unit assigned to it (key='unit') which are unconfirmed (confirmed='unconfirmed'). The returned tag assignments can now be easily confirmed or rejected to improve finding faulty datapoints or the machine learning system.

The relevant API endpoint is GET /v2/project/{project_id}/datapoints/byTag and the parameters are as follows:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

query

yes

The numeric id of the project from which to assign a tag.

1

key

string

query

yes

The key of the tags we filter for.

location

value

string

query

no

The value of the tags we filter for.

Office B113

source

string

query

no

The source of the tag assignment we filter for.

user

confirmed

string

query

no

The confirmed status of the assignment. Either "true" (correct assignment), "false" (incorrect assignment) or "unconfirmed" (unknown assignment).

"true"

Let us now query all datapoints we assigned a location tag to which are confirmed. Since we just confirmed the assignment before, we should get returned the just assigned tag to the datapoint.

Python
CURL
Swagger UI
Python
import requests
project_id = 1
r = requests.get(api_url + f"/v2/project/{project_id}/datapoints/byTag",
auth=john,
params={
'key': 'location',
'confirmed': 'unconfirmed',
})
print(r.status_code, r.json())
CURL
  1. Open a commandline.

  2. Execute the following command.

    curl 'https://api.aedifion.io/v2/project/1/datapoints/byTag?key=location'
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -H "Content-Type: application/json"
Swagger UI
  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 Datapoint tag ,then the GET /v2/project/{project_id}/datapoints/byTag endpoint (blue).

  4. Fill out the the neccessary parameters.

  5. Click "Try it out!".

  6. Inspect the response body and code.

We get the following list as result:

[
{
"dataPointID": "datapoint_within_your_office",
"tags": [
{
"confirmed": true
"id": 42,
"key": "location",
"protected": false,
"source": "user",
"value": "Office B113"
}
]
}
]

Deleting tag assignments

The Aedifion API allows you to delete tag assignments (remove tag from a datapoint) or to delete a tag entirely. You cannot delete a tag assignment which is protected. Also you cannot delete a tag completely from a project which has protected assignments or is assigned by another source as user (e.g. BACnet).

Deleting a tag or a tag assignment cannot be undone.

Let us now delete the assignment of the created location tag from the datapoint. For this we need the API endpoint DELETE /v2/datapoint/tag/{tag_id}. The parameters are as follows:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

query

yes

The numeric id of the project where the tag belongs to.

1

tag_id

integer

path

yes

The id of the tag we want to delete from the datapoint.

42

dataPointID

string

query

yes

The alphanumeric id of the datapoint from which we want to delete the tag.

datapoint_

within_

your_office

Python
CURL
Swagger UI
Python
import requests
project_id = 1
tag_id = 42
r = requests.delete(api_url + f"/v2/datapoint/tag/{tag_id}",
auth=john,
params = {
'dataPointID': 'datapoint_within_your_office',
'project_id': project_id,
})
print(r.status_code, r.json())
CURL
  1. Open a commandline.

  2. Execute the following command.

    curl 'https://api.aedifion.io/v2/datapoint/tag/42?
    dataPointID=datapoint_within_your_office&project_id=1'
    -X DELETE
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -H "Content-Type: application/json"
Swagger UI
  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 Datapoint tag ,then the DELETE /v2/datapoint/tag/{tag_id} endpoint (red).

  4. Fill out the the neccessary parameters.

  5. Click "Try it out!".

  6. Inspect the response body and code.

The result returns the tag and the datapoint from which the assignment was deleted.

{
"operation": "delete",
"resource": {
"datapoint": {
"dataPointID": "datapoint_within_your_office",
"project_id": 1
},
"tag": {
"id": 42,
"key": "location",
"value": "Office B113"
}
},
"success": true
}

The tag itself still exists in the system but it is no longer assigned to the datapoint.

Deleting Tags

If you want to delete the tag completely including all its assignments then you can use the following API method DELETE /v2/project/{project_id}/tag/{tag_id}.

You cannot delete a tag if it is assigned by another source (e.g. automatically assigned tags by BACnet) or has protected assignments.

The parameters for the API endpoint are the following:

Parameter

Datatype

Type

Required

Description

Example

project_id

integer

path

yes

The numeric id of the project from which to delete a tag.

1

tag_id

integer

path

yes

The id of the tag we want to delete.

42

Python
CURL
Swagger UI
Python
import requests
project_id = 1
tag_id = 42
r = requests.delete(api_url + f"/v2/project/{project_id}/tag/{tag_id}",
auth=("email", "password"))
print(r.status_code, r.json())
CURL
  1. Open a commandline.

  2. Execute the following command.

    curl https://api.aedifion.io/v2/project/1/tag/42
    -X DELETE
    -u john.doe@aedifion.com:mys3cr3tp4ss0wrd
    -H "Content-Type: application/json"
Swagger UI
  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 DELETE /v2/project/{project_id}/tag/{tag_id} endpoint (red).

  4. Fill out the the neccessary parameters.

  5. Click "Try it out!".

  6. Inspect the response body and code.

When the operation is successful the deleted tag is returned. This operation cannot be undone!

{
"operation": "delete",
"resource": {
"id": 42,
"key": "location",
"value": "Office B113"
},
"success": true
}