Get the layout of the building

GET

/v1/buildings/{building_id}/topology

curl --request GET \
  --url https://example.com/v1/buildings/example/topology \
  --header 'X-Api-Key: <X-Api-Key>'

The locations of the building and where each point is (profile https://w3id.org/buildinglinks/v1/topology). A backend may serve only this operation: a topology source, such as an installer’s BIM model.

Authorizations

• bindingKey

Parameters

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

point_ids

string

Only these points, and only the locations they are in with everything above them. A comma-separated list (a,b) or the parameter repeated; at least one id.

Responses

200

The layout.

TopologyResponse

Response of GET /v1/buildings/{building_id}/topology (profile https://w3id.org/buildinglinks/v1/topology, decision #71): the locations of the building and where each point is. Point ids are those of the source. With point_ids only those points, and only the locations they are in with everything above them (part_of).

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

locations

required

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

points

required

Array<object>

object

point_id

required

Stable address of a point, for example 9b41d0aa.

string

>= 1 characters

location_id

required

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

string

>= 1 characters

Example ^generated

{
  "buildinglinks_version": "example",
  "building_id": "example",
  "locations": [
    {
      "location_id": "example",
      "name": "example",
      "class": "example",
      "part_of": "example"
    }
  ],
  "points": [
    {
      "point_id": "example",
      "location_id": "example"
    }
  ]
}

TopologyResponse

Response of GET /v1/buildings/{building_id}/topology (profile https://w3id.org/buildinglinks/v1/topology, decision #71): the locations of the building and where each point is. Point ids are those of the source. With point_ids only those points, and only the locations they are in with everything above them (part_of).

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

locations

required

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

points

required

Array<object>

object

point_id

required

Stable address of a point, for example 9b41d0aa.

string

>= 1 characters

location_id

required

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

string

>= 1 characters

Example ^generated

{
  "buildinglinks_version": "example",
  "building_id": "example",
  "locations": [
    {
      "location_id": "example",
      "name": "example",
      "class": "example",
      "part_of": "example"
    }
  ],
  "points": [
    {
      "point_id": "example",
      "location_id": "example"
    }
  ]
}

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

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

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

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

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

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

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

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

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

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