Read the current values

GET

/gateway/{alias}/v1/buildings/{building_id}/points/values

curl --request GET \
  --url https://example.com/gateway/example/v1/buildings/example/points/values \
  --header 'Authorization: Bearer <token>'

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

Authorizations

• appKey
• appKeyHeader
• controlPlane

Parameters

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

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

200

The readings.

Media typeapplication/json

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

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

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

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

object

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

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

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

object

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

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

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

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

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

object

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