> For the complete documentation index, see [llms.txt](https://docs.dataclearinghouse.org/dch-2.0-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dataclearinghouse.org/dch-2.0-documentation/walkthroughs/finding-points.md).
# Finding Points
Within DCH, a Point is a [virtual entity](https://docs.brickschema.org/brick/concepts.html#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](https://beta.dataclearinghouse.org/api/aletheia/v1/swagger#/Point/get_points) 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: '
```
We may receive information on Points across a variety of organisations and data pools, e.g.
**Response:**
```json
[
{
"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. `::`
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: '
```
We receive information only about the Points within the `org_b` organisation.
**Get points by organisation - response:**
```json
[
{
"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](https://develop.dataclearinghouse.org/api/aletheia/v1/swagger#/Data%20Pool/get_datapools__id_). 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: '
```
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:**
```json
[
{
"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: '
```
We receive information about the Points across all datapools and organisations that start with `dsapi-example.`
**Get points by point identifier - response:**
```json
[
{
"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:
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: ; rel="next",; rel="first"
```