Group View

The VAPIX® Group View API provides the information that makes it possible to configure the channel layout in a Group View configuration. A group view consists of multiple channels, most commonly in a quad (four channels) or dual (two channels) setup. The API is used when you want to configure or rearrange the layout of or the channels found in the group view.

Overview

The API implements groupview.cgi as its communications interface and supports the following methods:

Method	Description
getLayout	Request the layout for the channels in the group view.
getAvailableLayout	Request possible layouts available to the group view.
setLayout	Set the layout for the channels in the group view.
getSupportedVersions	List supported API versions.

This diagram exemplifies how the group view layout can be changed. In this case, the API has been used to mirror the layout, so that the first channel starts in the top right corner instead of the top left.

Identification

API Discovery: id=groupview

Common examples

Request channel layout

This example will show you how to check the current channel layout in the group view.

1. Check the channel layout of a specific group view. The id-number parameter is used to identify the channel.

http://<servername>/axis-cgi/groupview.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getLayout",
  "params": {
    "id": 5
  }
}

2. Parse the JSON response. The API will return a quad view that reads from top left to bottom right.

Successful response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getLayout",
  "data": {
    "id": 5,
    "layout": [
      [
        {"id": 1}, {"id": 2}
      ],
      [
        {"id": 3}, {"id": 4}
      ]
    ]
  }
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getLayout",
  "error": {
    "code": 2100,
    "message": "API version not supported"
  }
}

See getLayout for additional details.

Request potential channel layouts

This example will show you how to request the different ways to configure the channel layout for the group view. Different devices will have different available options for the group view.

1. Check the channel layouts for a specific group view with an id-number.

http://<servername>/axis-cgi/groupview.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getAvailableLayout",
  "params": {
    "id": 5
  }
}

2. Parse the JSON response. The API will return possible layouts for the channels in the group view.

Successful response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getAvailableLayout",
  "data": [
    {
      "id": 5,
      "layout": [
        [
          [{"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}],
          [{"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}]
        ],
        [
          [{"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}]
        ],
        [
          [{"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}]
        ]
      ]
    }
  ]
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getAvailableLayout",
  "error": {
    "code": 2100,
    "message": "API version not supported"
  }
}

See getAvailableLayout for additional details.

Request all available channel layouts

This example will show you how to check every possible channel layout from the group view.

1. Request all available channel layouts from the group view.

http://<servername>/axis-cgi/groupview.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getAvailableLayout",
  "params": {
  }
}

2. Parse the JSON response. The API will return the possible layouts for all group view channels.

Successful response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getAvailableLayout",
  "data": [
    {
      "id": 5,
      "layout": [
        [
          [{"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}],
          [{"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}]
        ],
        [
          [{"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}]
        ],
        [
          [{"id": [1, 2, 3, 4]}, {"id": [1, 2, 3, 4]}]
        ]
      ]
    },
    {
      "id": 6,
      "layout": [
        [
          [{"id": [1, 2]}, {"id": [3, 4]}]
        ]
      ]
    }
  ]
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getAvailableLayout",
  "error": {
    "code": 2100,
    "message": "API version not supported"
  }
}

See getAvailableLayout for additional details.

Set channel layouts for the group view

This example will show you how to rearrange the channel layout for the group view.

1. Rearrange the channel layout for the group view.

http://<servername>/axis-cgi/groupview.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setLayout",
  "params": {
    "id": 5,
    "layout": [
      [{"id": 1}, {"id": 3}],
      [{"id": 4}, {"id": 2}]
    ]
  }
}

2. Parse the JSON response. The API will return the new group view layout.

Successful response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setLayout",
  "data": {
    "id": 5,
    "layout": [
      [{"id": 1}, {"id": 3}],
      [{"id": 4}, {"id": 2}]
    ]
  }
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "setLayout",
  "error": {
    "code": 1100,
    "message": "Internal error"
  }
}

See setLayout for additional details.

List supported API versions

This example will show you how to check the API versions supported by your device.

1. Request a list of supported API versions.

http://<servername>/axis-cgi/groupview.cgi

Request body syntax

{
  "context": "123",
  "method": "getSupportedVersions",
}

2. Parse the JSON response.

Successfully response example

{
  "context": "123",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["1.4", "2.5"]
  }
}

Error response example

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSupportedVersions",
  "error": {
    "code": 2100,
    "message": "API version not supported"
  }
}

See getSupportedVersions for additional details.

API specifications

getLayout

This should be used when you want to check the channel layout of a group view.

Request

Security level: Operator
Method: POST

http://<servername>/axis-cgi/groupview.cgi

JSON input parameters

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getLayout",
  "params": {
    "id": <int>
  }
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>` Optional	The user sets this value and the application echoes it back in the response.
`method="getLayout"`	The method that should be used.
`id=<integer>`	The ID of the group view that the user wants to check.

Return value - Success

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getLayout",
  "data": {
    "id": <int>,
    "layout": [
      [{"id": <int>}, {"id": <int>}],
      [{"id": <int>}, {"id": <int>}]
    ]
  }
}

Parameter	Sub-parameter	Description
`apiVersion`		The API version returned from the request.
`context=<string>` Optional		The context set by the user in the request.
`method="getLayout`		The requested method.
`id=<integer>`		The ID of the group view returned by the request.
`layout=<list of rows>`		The current channel layout of the group view. Contains listings of layouts and columns. The first list is for the first row, the second list is for the second row and so on.
	`<list of channels>`	List the rows in the group view. The first element contains information about the first channel, starting from the left, the second element contains the second channel and so on. Each channel element contains the information on how a specific channel in a specific location in the group view has been configured.
	`id=<integer>`	Specifies the channel and its location in the group view.

Return value - Failure

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getLayout",
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

See General error codes for a complete list of potential errors.

getAvailableLayout

This method should be used when you want to check a list of possible layouts that are available for the group view.

Request

Security level: Operator
Method: POST

http://<servername>/axis-cgi/groupview.cgi

JSON input parameters

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getAvailableLayout",
  "params": {
    "id": <int>
  }
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>` Optional	The user sets this value and the application echoes it back in the response.
`method="getAvailableLayout"`	The method that should be used.
`id=<integer>` Optional	The ID for the group view that the user wants to check. Omitting this parameter will make the response contain possible layouts for every ID supporting group view.

Return value - Success

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "context": <string>,
  "method": "getAvailableLayout",
  "data": [
    {
      "id": <int>,
      "layout": [
        [
          [{"id": [<int>, <int>, <int>, <int>]}, {"id": [<int>, <int>, <int>, <int>]}],
          [{"id": [<int>, <int>, <int>, <int>]}, {"id": [<int>, <int>, <int>, <int>]}]
        ],
        [
          [{"id": [<int>, <int>, <int>, <int>]}, {"id": [<int>, <int>, <int>, <int>]}]
        ]
      ]
    },
    {
      "id": <int>,
      "layout": [
        [
          [{"id": [<int>, <int>]}, {"id": [<int>, <int>]}]
        ]
      ]
    }
  ]
}

Parameter	Sub-parameter	Description
`apiVersion`		The API version returned from the request.
`context=<string>` Optional		The context set by the user in the request.
`method="getAvailableLayout`		The requested method.
`data=<list of data>`		Object list with ID and attributes. The list will contain one element if the ID was set in the request, as long as it supports group view. The request will fail if the ID does not support group view
	`id=<integer>`	The ID of the group view layout returned by the request.
	`layout=<list of layouts>`	List the layouts that can be set in the group view. Each layout contains different rows of channels that represents layouts and columns in the group view. The first list is for the initial row, the second for the next row and so on. The first element contains information about the first channel, starting from the left, the second element contains the next channel and so on. Each channel element also contains the information how a channel in a specific location in the group view can be configured. The channel element also has information about the channel ranges that can be set in a specific position.
	`id=<list>`	Provides a list of channel IDs that are possible to set in a specific position.

Return value - Failure

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getAvailableLayout",
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

See General error codes for a complete list of potential errors.

setLayout

This method should be used when you want to configure the channel layout in a group view.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/groupview.cgi

Request body syntax

{
  "apiVersion": "1.0",
  "context": <string>,
  "method": "setLayout",
  "params": {
    "id": <int>,
    "layout": [
      [{"id": <int>}, {"id": <int>}],
      [{"id": <int>}, {"id": <int>}]
    ]
  }
}

Parameter	Sub-parameters	Description
`apiVersion`		The API version that should be used.
`context=<string>` Optional		The user sets this value and the application echoes it back in the response.
`method="setLayout"`		The method that should be used.
`id=<integer>`		The group view ID that the user wants to set the layout for.
`layout=<list of rows>`		Specifies the new channel layout that will be set in the group view. Contains both the layouts and columns in the group view. The first list is for the initial row, the seconds is for the next row and so on.
	`<list of channels>`	Contains a list for a specific row in the group view. The first element contains information about the first channel, starting from the left, the second element contains the next channel and so on. Each channel element contains the information how a channel in a specific location in the group view can be configured.
	`id=<integer>`	Specifies a channel location in the group view.

Return value - Success

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "context": <string>,
  "method": "setLayout",
  "data": {
    "id": <int>,
    "layout": [
      [{"id": <int>}, {"id": <int>}],
      [{"id": <int>}, {"id": <int>}]
    ]
  }
}

Parameter	Sub-parameters	Description
`apiVersion`		The API version that should be used.
`context=<string>` Optional		The context set by the user in the request.
`method="setLayout"`		The requested method.
`id=<integer>`		The group view ID of the layout set by the request.
`layout=<list of rows>`		The new channel layout set in the group view. Contains both the layouts and columns in the group view. The first list is for the initial row, the seconds is for the next row and so forth.
	`<list of channels>`	Contains a list for a specific row in the group view. The first element contains information about the first channel, starting from the left, the second element contains the next channel and so forth. Each channel element contains the information how a channel in a specific location in the group view can be configured.
	`id=<integer>`	Specifies a channel location in the group view.

Return value - Failure

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "setLayout",
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

See General error codes for a complete list of potential errors.

getSupportedVersions

This method should be used when you want to request a list of supported API versions.

Request

Security level: Operator
Method: POST

http://<servername>/axis-cgi/groupview.cgi

Request body syntax

{
  "context": <string>,
  "method": "setLayout",
}

Parameter	Description
`context=<string>` Optional	The user sets this value and the application echoes it back in the response.
`method="getSupportedVersions"`	The method that should be used.

Return value - Success

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["<Major1>.<Minor1>", "<Major2>.<Minor2>"]
  }
}

Parameter	Sub-parameters	Description
`context=<string>` Optional		The context set by the user in the request.
`method="getSupportedVersions"`		The requested method.
`data.apiVersions[]=<list of versions>`		List of all supported major API versions along with their highest supported minor version.
	`<list of versions>`	List of "<Major>.<Minor>" versions e.g. ["1.4", "2.5"]

Return value - Failure

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "getSupportedVersions",
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

See General error codes for a complete list of potential errors.

JSON code	HTTP code	Description
`1200`	`500`	List does not match an allowed layout.
`2200`	`400`	Invalid value for ID in parameter layout.

General error codes

The following table consist of errors that may occur for any method. Errors specific to a method are listed under their separate API description. The error codes exist in the following ranges.

1100–1199

Generic error codes common for many APIs and reserved for server errors such as "Maximum number of configurations reached". The actual cause can be seen in the server log and can sometimes be solved by restarting the device.
1200–1999

API-specific server errors that may collide between different APIs.
2100–2199

Generic error codes common to many APIs and reserved for client errors such as "Invalid parameter". These errors should be possible to solve by changing the input data to the API.
2200–2999

API-specific client errors that may collide between different APIs.

note

The 4–digit error codes are returned in the JSON body when the service is executed, which means that the client must be prepared to handle transport-level errors codes with non-JSON responses. Specifically, HTTP error 401/403 will be emitted if either authentication or authorization fails.

JSON code	HTTP code	Description
`1100`	`500`	Internal error.([^1])
`2100`	`400`	API version not supported.
`2101`	`400`	Invalid JSON.
`2102`	`400`	Method not supported.
`2103`	`400`	Required parameter missing.
`2104`	`400`	Invalid parameter value specified.
`2105`	`403`	Authorization failed.
`2106`	`401`	Authentication failed.
`2107`	`4XX, 5XX`	Transport-level error.

[1]: Out-of-memory errors will also be reported as 1100 Internal error.

Overview​

Identification​

Common examples​

Request channel layout​

Request potential channel layouts​

Request all available channel layouts​

Set channel layouts for the group view​

List supported API versions​

API specifications​

getLayout​

getAvailableLayout​

setLayout​

getSupportedVersions​

General error codes​

Overview

Identification

Common examples

Request channel layout

Request potential channel layouts

Request all available channel layouts

Set channel layouts for the group view

List supported API versions

API specifications

getLayout

getAvailableLayout

setLayout

getSupportedVersions

General error codes