Ga naar inhoud
buildinglinksbuildinglinks

Discover the points of a building

GET
/gateway/{alias}/v1/buildings/{building_id}/points
curl --request GET \
  --url 'https://example.com/gateway/example/v1/buildings/example/points?class=brick%3AZone_Air_Temperature_Sensor&access=read&flow_direction=consumption&include=equipment%2Cgroups%2Clocations' \
  --header 'Authorization: Bearer <token>'

The points of the building with their class, access, unit and constraints, filtered by the query. With include, also equipment, groups and locations.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
alias
required
string

The connection (abonnement) to call through, as Verbindingen in the connector names it.

building_id
required

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters

The object id of the building: its register identification in dotted form, e.g. nl.bag.pand.0014100040022681.

Query Parameters

Section titled “Query Parameters”
class
string

Points of this Brick class and everything beneath it, as a CURIE such as brick:Sensor. An equipment or system class selects the points of that equipment.

access
Allowed values: read write read_write

Points that allow at least this access.

flow_direction
Allowed values: consumption production delivery return_delivery charge discharge

Points with this flow direction.

point_ids
string

Only these points. A comma-separated list (a,b) or the parameter repeated; at least one id.

modified_since
string format: date-time

Points whose metadata changed after this moment (RFC 3339).

include
string

Adds to the answer, comma-separated: equipment, groups (named asset groups, an extension) and locations (draft v2).

Responses

Section titled “Responses”

200

Section titled “200”

The points.

Media typeapplication/json
DiscoverResponse

Response of GET /v1/buildings/{building_id}/points.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id
required

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
generated_at
required

RFC 3339 timestamp.

string format: date-time
points
required
Array<object>
Point

One data source or actuator in the building (message 1).

object
point_id
required

Stable address of a point, for example 9b41d0aa.

string
>= 1 characters
name
required
string
class
required

Brick class.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
access
required
Allowed values: read write read_write
value_type
required
Allowed values: number integer boolean string
is_cumulative
required
boolean
unit

QUDT unit; present when numeric.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
constraints
object
min
number
max
number
step
number
> 0
minimum_interval

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
flow_direction
Allowed values: consumption production delivery return_delivery charge discharge
equipment_id
string
location_id

V2 draft: where the point is, see include=locations.

string
>= 1 characters
equipment

Present with include=equipment.

Array<object>
Equipment

An asset that owns points, with optional grid connection ratings.

object
equipment_id
required
string
>= 1 characters
class
required

Compact IRI such as brick:Temperature_Sensor or unit:DEG_C.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
name
string
is_fed_by
string
location_id

V2 draft: where the equipment stands.

string
>= 1 characters
capacity
object
rated_power_output
object
value
required
number
unit

Compact IRI such as brick:Temperature_Sensor or unit:DEG_C.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
rated_power_input
object
value
required
number
unit

Compact IRI such as brick:Temperature_Sensor or unit:DEG_C.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
rated_max_current_input
object
value
required
number
unit

Compact IRI such as brick:Temperature_Sensor or unit:DEG_C.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
phase_count
object
value
required
number
unit

Compact IRI such as brick:Temperature_Sensor or unit:DEG_C.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
groups

Extension, present with include=groups: named asset groups for target.group_id.

Array<object>
object
group_id
required
string
name
string
equipment_ids
required
Array<string>
locations

V2 draft, present with include=locations: the building, its levels, rooms and zones.

Array<object>
Location

V2 draft: a place in the building (the building, a level, a room or a zone). Classes come from RealEstateCore, for example rec:Building, rec:Level, rec:Room, rec:Zone and rec:HVACZone.

object
location_id
required

Id of a location returned with include=locations (v2 draft).

string
>= 1 characters
name
required
string
class
required

RealEstateCore (rec:) or Brick location class.

string
/^([A-Za-z0-9_-]+:[A-Za-z0-9_.-]+|https?://.+)$/
part_of

The enclosing location; absent for the building itself.

string
>= 1 characters

Example 

{
  "points": [
    {
      "access": "read",
      "value_type": "number",
      "flow_direction": "consumption"
    }
  ]
}

400

Section titled “400”

invalid_request, or a write the backend refuses as a whole (point_not_writable, value_out_of_range, …).

Media typeapplication/json
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

401

Section titled “401”

From the backend: unauthenticated: no or a wrong key. From the gateway: unauthenticated: no key, an unknown key, or an invalid token of the control plane.

Media typeapplication/json
Any of:
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

403

Section titled “403”

From the backend: forbidden: the key may not use this building. From the gateway: forbidden: the key lacks the gateway scope, its app may not use this connection, or the app may only read. The provider’s data plane refuses with 403 what the agreement does not cover.

Media typeapplication/json
Any of:
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

404

Section titled “404”

building_not_found, or not_found for an unknown route.

Media typeapplication/json
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}

502

Section titled “502”

upstream_unavailable: the provider’s data plane could not be reached, its answer was larger than 16 MiB, or, when the agreement requires signed requests, its answer had no valid signature.

Media typeapplication/json

An answer of the gateway itself, not one it passes on.

object
error
required
object
code
required
string
message
required
string
retryable
required

Whether the same request may succeed later.

boolean

Example 

{
  "error": {
    "code": "forbidden"
  }
}

503

Section titled “503”

From the backend: upstream_unavailable: the building’s systems cannot be reached; retryable. From the gateway: upstream_unavailable: the connection is not active (yet), or renewing the access token failed; evidence_unavailable: the agreement requires signed requests and the request or answer could not be recorded; standby: another instance of this data plane is active. Retryable.

Media typeapplication/json
Any of:
ErrorResponse

Body of every 4xx and 5xx response. building_id is present when the request addressed a building.

object
buildinglinks_version
required

Protocol version, carried by every response.

string
/^1\.[0-9]+$/
building_id

Object id of the building: the register identification in dotted form, for example nl.bag.pand.0014100040022681.

string
>= 1 characters
error
required
object
code
required

Invalid_request, unauthenticated, building_not_found, point_not_writable, value_out_of_range, unit_mismatch, rate_limited and upstream_unavailable come from the proposal. forbidden, point_not_found, type_mismatch, target_not_found, command_not_supported, expired, not_found and internal are extensions. Clients must accept unknown codes.

string
message
required
string
retryable
required
boolean
target

Which field caused it, for example setpoints[0].value.

string
retry_after

ISO 8601 duration with exact units only (W, D, H, M, S), for example PT15M.

string
/^P(?!$)([0-9]+([.,][0-9]+)?W)?([0-9]+([.,][0-9]+)?D)?(T(?=[0-9])([0-9]+([.,][0-9]+)?H)?([0-9]+([.,][0-9]+)?M)?([0-9]+([.,][0-9]+)?S)?)?$/
details
Array<object> recursive

Example 

{
  "error": {
    "code": "invalid_request"
  }
}