Ga naar inhoud
buildinglinksbuildinglinks

Read the current values

GET
/v1/buildings/{building_id}/points/values
curl --request GET \
  --url https://example.com/v1/buildings/example/points/values \
  --header 'X-Api-Key: <X-Api-Key>'

The latest reading of each requested point. Every requested point appears in readings or in unavailable, with a reason.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
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”
point_ids
string

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

max_age

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)?)?$/

An ISO 8601 duration such as PT15M: older readings move to unavailable with reason too_stale. Default: any age.

Responses

Section titled “Responses”

200

Section titled “200”

The readings.

ReadingsResponse

Response of GET /v1/buildings/{building_id}/points/values. Every requested point appears in exactly one of the two arrays.

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
readings
required
Array<object>
object
point_id
required

Stable address of a point, for example 9b41d0aa.

string
>= 1 characters
timestamp
required

RFC 3339 timestamp.

string format: date-time
value
required

Matches the point’s value_type.

number | integer | boolean | string
quality
required
Allowed values: ok stale
unavailable
required
Array<object>
object
point_id
required

Stable address of a point, for example 9b41d0aa.

string
>= 1 characters
reason
required
Allowed values: no_data too_stale not_found forbidden

Example 

{
  "readings": [
    {
      "quality": "ok"
    }
  ],
  "unavailable": [
    {
      "reason": "no_data"
    }
  ]
}

400

Section titled “400”

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

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”

unauthenticated: no or a wrong key.

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”

forbidden: the key may not use this building.

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.

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"
  }
}

503

Section titled “503”

upstream_unavailable: the building’s systems cannot be reached; retryable.

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"
  }
}