search

Finding Points

Within DCH, a Point is a virtual entityarrow-up-right 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.

hashtag
Finding Points by identifier

DCH's GET /points endpointarrow-up-right allows a user to find points under a set of filters.

With a request get points:

curl -X 'GET' \
  'https://dataclearinghouse.org/api/aletheia/v1/points' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: <API KEY>'

We may receive information on Points across a variety of organisations and data pools, e.g.

Response:

[
  {
    "id": "dsapi-example-point-identifier",
    "uid": "33b199a8-9eaa-4d75-b4dc-c70aa66a7570",
    "organisationId": "org_a",
    "datapoolId": "org_a:datasource_a",
    "name": "dsapi-example-point-identifier",
    "type": "brick:Point",
    "unit": null,
    "compositeId": "org_a:datasource_a:dsapi-example-point-identifier"
  },
  {
    "id": "dsapi-my-new-stream",
    "uid": "33b199a8-9eaa-4d75-b4dc-c70aa66a7570",
    "organisationId": "org_b",
    "datapoolId": "org_b:test_datasource",
    "name": "Example stream",
    "type": "brick:Point",
    "unit": null,
    "compositeId": "org_b:test_datasource:dsapi-my-new-stream"
  },
  {
    "id": "dsapi-big-funny-plant-stream1",
    "uid": "33b199a8-9eaa-4d75-b4dc-c70aa66a7570",
    "organisationId": "test_organisation",
    "datapoolId": "test_organisation:test_datasource",
    "name": "dsapi-big-funny-plant-stream1",
    "type": "brick:Point",
    "unit": null,
    "compositeId": "test_organisation:test_datasource:dsapi-big-funny-plant-stream1"
  }
]

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.

hashtag
By organisation identifier

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:

hashtag
By data pool identifier

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 GET datapool by ID endpointarrow-up-right. Using the composite ID, we can make an updated request.

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:

hashtag
By point identifier

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:

hashtag
Paginating through the Points API in DCH

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.

To use the /points API, you can check out the docs right here: https://beta.dataclearinghouse.org/api/aletheia/v1/swagger#/Point/get_pointsarrow-up-right

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

PreviousAuthenticating with DCH APINextUsing BRIQL query to find points

Last updated