Finding Points

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

Finding Points by identifier

DCH's GET /points endpoint 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.

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:

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

We receive information only about the Points within the org_b organisation.

Get points by organisation - response:

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

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 endpoint. Using the composite ID, we can make an updated request.

Get points by data pool - request:

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

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:

[
  {
    "id": "dsapi-big-funny-plant-stream1",
    "uid": "33b199a8-9eaa-4d75-b4dc-c70aa66a7570",
    "organisationId": "org_b",
    "datapoolId": "org_b:test_datasource",
    "name": "dsapi-big-funny-plant-stream1",
    "type": "brick:Point",
    "unit": null,
    "compositeId": "org_b:test_datasource:dsapi-big-funny-plant-stream1"
  }
]

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:

curl -X 'GET' \
  'https://dataclearinghouse.org/api/aletheia/v1/points?id=org_b:dsapi-example*' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: <API KEY>'

We receive information about the Points across all datapools and organisations that start with dsapi-example.

Get points by point identifier - 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-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"
  }
]

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_points

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

link: <https://beta.dataclearinghouse.org/api/aletheia/v1/points?after=ff481f89-51db-4e92-be89-c3923052264b&limit=100>; rel="next",<https://beta.dataclearinghouse.org/api/aletheia/v1/points?limit=100>; rel="first"

PreviousAuthenticating with DCH API NextUsing BRIQL query to find points

Last updated 11 months ago