Finding Points
Last updated
Last updated
Within DCH, a Point is a representing a distinct channel of information flow. Some examples of Points include an import real power sensor Point attached to an electrical meter, or an outside temperature sensor Point related to a weather station. Within DCH, Points belong to a Data Pool and can be linked to a Building or Site Model.
Points can be discovered based on identifiers related to the point (e.g. point identifier, organisation identifier or data pool identifier), or by querying site and building models for points based on the type or metadata associated with the point.
DCH's allows a user to find points under a set of filters.
With a request get points:
We may receive information on Points across a variety of organisations and data pools, e.g.
Response:
Here, the response has Points across three different datapools within two different organisations. Within reach element in the response there are multiple identifiers, each with a different purpose:
id: Simple non-unique identifier for the point
uid: Universally unique identifier (UUID4) for the point
organisationId: The unique identifier for the organisation in which the point belongs to
datapoolId: Unique identifier for the datapool within which the point is stored
compositeId: A unique identifier for the point, composed of the organisation identifier, datapool identifier and point non-unique identifier delimited by a colon, i.e. <organisationId>:<datapoolId>:<id>
We can then restrict our search based on these fields.
By using the query parameter organisationid, we can filter to find only those points registered to the org_b organisation.
Get points by organisation - request:
We receive information only about the Points within the org_b organisation.
Get points by organisation - response:
Get points by data pool - request:
We receive information only about the Points within the org_b organisation (and we do not receive any Points registered to the test_datasource datapool under the org_a organisation).
Get points by data pool - response:
We can filter the point identifier directly using the query parameter id. This identifier is not unique across multiple datapools, and so you may get multiple points with the same point identifier (but different datapool identifiers and/or organisation identifiers). Using a point identifier search with wildcard *, we can make an updated request.
Get points by point identifier - request:
We receive information about the Points across all datapools and organisations that start with dsapi-example.
Get points by point identifier - response:
DCH's API uses the link header to allow the user to paginate through resources. If you wanted to look at all the points linked to a specific data pool, you can paginate effectively using these headers.
Some pointers:
DCH's pagination is cursor-based. If you do not have a cursor, you cannot proceed to a given page.
The link header will always be present in a response, even if there are no more pages.
The link header separates different links using a comma character.
If there is a new page to visit, you will see a next link.
If there is a previous page to visit, you will see a prev link.
There will always be a first link to enable you to reset back to the start of the search set.
You can set a limit to change your page size using the limit query parameter.
Link Header Example
Similarly, by using the query parameter datapoolid, we can filter to find only those points registered to the test_datasource datapool within the org_b organisation. This can be performed by referencing the datapool in two ways, that is, either via the composite id org_b:test_datasource or by the datapool unique identifier, which can be obtained by requesting additional information about the datapool via DCH's . Using the composite ID, we can make an updated request.
To use the /points API, you can check out the docs right here: