Get room zones information

📘
Only HDL410 systems support this feature.

Returns the zone information of the connected Nureva® audio conferencing system’s room.

A zone is an area, up to the size of the whole room, that has a label and a type. A room is composed of 0 or more user defined zones. Zones of the same type may not overlap but zones of different types may overlap, and all zones must be entirely contained within a room.

When a sound location event occurs within a room, the sound can trigger the 1 or more zones that encompass the sound location. It is possible for a single sound location event to trigger 0 or more zones, but as stated above, if multiple zones are triggered by the same sound location event, they would need to be zones of different types.

Zones are configurable by end users through Nureva Console software.

Learn more about zones

Request

{ 
  "request": "v1/room/zones", 
  "requestId": string, 
  "clientId": string 
}

Response

{
  "request": "v1/room/zones",
  "requestId": string,
  "clientId": string,
  "body": {
    "zones": {    
      "types": ["Switching"],
      "geometry": { 
        "point1": {
          "x": number,
          "y": number,
        },
        "point2": {
          "x": number,
          "y": number,
        },
      },
      "label": string,
      "id": string,
    }[]
  }
}

types	An array of 1 or more strings defining the purpose of this zone. Presently, the only possible type of zone is "Switching" indicating that this zone is intended to define support for camera switching within this room. It is not possible for the same type of zone to appear more than once within this array.
geometry	Position of the zone in room coordinates, as defined in Get room layout information, where the southwest corner of the room is taken as the origin (0,0) of the coordinate system. All zones are rectangular or square with their bounding box defined by the point1 and point2 properties on opposite corners. point1: The x and y location, in room coordinates, of one corner of the zones’ bounding box in millimeters. point1 is the opposite corner to point2. point2: The x and y location, in room coordinates, of one corner of the zones’ bounding box in millimeters. point2 is the opposite corner to point1.
label	The meaningful name given to the zone when defined through Nureva Console. This identifier should be human readable.
id	A unique identifier for the zone that is not intended to be human readable.

Errors

Status code	Description
10000 – Bad request	Request does not conform to the specification. The message field will include detailed information about which part of the request is incorrect.
11000 – Unsupported device	Connected hardware device does not support audio location streaming.
11001 – Device not connected	No audio device is connected.
11006 – Room information unavailable	Room information unavailable.
11008 – Zone information unavailable	Zone information unavailable.

Sample requests

1. Valid request/response

Request

{
  "request": "v1/room/zones",
  "requestId": "1234",
  "clientId": "1111"
}

Response

{
  "request": "v1/room/zones",
  "requestId": "1234",
  "clientId": "1111",
  "body": {
    "zones": [
      {
        "types": ["Switching"],
        "geometry": { 
          "point1": {
            "x": 0,
            "y": 0
          },
          "point2": {
            "x": 4567,
            "y": 7294
          },
        },
        "label": "Front of room",
        "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
      }
    ]
  }
}

2. Unsupported device

This is a valid request. However, in this fictitious example, the device is an HDL300 which doesn’t support zones capabilities so it returns an error.

Request

{
  "request": "v1/room/zones",
  "requestId": "1234",
  "clientId": "1111"
}

Response

{
  "request": "v1/room/zones",
  "requestId": "1234",
  "clientId": "1111",
  "errors": [
    {
      "statusCode": 11000,
      "message": "Unsupported device"
    }
  ]
}