PTZ Orientation Aid API

Description

The PTZ Orientation Aid API allows an administrator to add a compass as an overlay to the video. This makes it easier for the operator to provide relevant information to other personnel, for instance "The burglar is running west on Main Street".

Identification

API Discovery: id=ptz-orientationaid

Authorization

DigestAuth: Admin, Operator
BasicAuth: Admin, Operator

Use cases

Set north direction

Use the setNorth method to set the direction that the camera is pointing to as north.

Get compass state

Use the getCompassState method to get the compass state.

Set compass state

Use the getCompassState method to to get the compass state.
Use the setCompassState method to to set the compass state.

Use the listTags method to get a list of all available tags.

Show or hide the tags for the preset positions

Use the listTags method to get a list of all available tags.
Use the setTagState method to show or hide the preset positions in the device web interface.

API specifications

setNorth

Use this method to set the direction that the camera is pointing to as north. You need to set it again whenever the camera position changes.

Request

curl
HTTP

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/axis-cgi/ptz-orientationaid.cgi" \
  --data '{
    "apiVersion": "2.0",
    "context": "example",
    "method": "setNorth"
}'

POST /axis-cgi/ptz-orientationaid.cgi
Host: <servername>
Content-Type: application/json

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "setNorth"
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that should be used.

Response - Success

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "setNorth",
    "data": {}
}

Parameters	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that was performed.
`data`	Object	Contains response specific parameters.

Response - Error

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "setNorth",
    "error": {
        "code": 2003,
        "message": "The requested API version is not supported."
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The performed method.
`error`	Object	The error object.
`error.code`	Integer	The error code.
`error.message`	String	The error message for the corresponding error code.

Error codes

See General error codes for a list of potential errors.

getCompassState

Use this method to check if compass has been enabled.

Request

curl
HTTP

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/axis-cgi/ptz-orientationaid.cgi" \
  --data '{
  "apiVersion": "2.0",
  "context": "example",
  "method": "getCompassState"
}'

POST /axis-cgi/ptz-orientationaid.cgi
Host: <servername>
Content-Type: application/json

{
  "apiVersion": "2.0",
  "context": "example",
  "method": "getCompassState"
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that should be used.

Response - Success

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "getCompassState",
    "data": {
        "enabled": true
    }
}

Parameters	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that was performed.
`data`	Object	Contains response specific parameters.
`data.enabled`	Boolean	Indicates if compass is enabled.

Response - Error

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "getCompassState",
    "error": {
        "code": 2003,
        "message": "The requested API version is not supported."
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The performed method.
`error`	Object	The error object.
`error.code`	Integer	The error code.
`error.message`	String	The error message for the corresponding error code.

Error codes

See General error codes for a list of potential errors.

setCompassState

Use this method to enable compass.

Request

curl
HTTP

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/axis-cgi/ptz-orientationaid.cgi" \
  --data '{
  "apiVersion": "2.0",
  "context": "example",
  "method": "setCompassState",
  "params": {
    "enabled": true
  }
}
~~~

| Parameter | Type | Description |
| --- | --- | --- |
| `apiVersion` | String | The API version that was used. |
| `context` | String | The context that was used when the request was made (optional). |
| `method` | String | The method that should be used. |
| `params` | Object | Contains method specific parameters. |
| `params.enable` | Boolean | States if the compass should be enabled. `true` = enabled or `false` = disabled. |

**Response - Success**

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

```json
{
  "apiVersion": "2.0",
  "context": "example",
  "method": "setCompassState",
  "data": {}
}'

POST /axis-cgi/ptz-orientationaid.cgi
Host: <servername>
Content-Type: application/json

{
  "apiVersion": "2.0",
  "context": "example",
  "method": "setCompassState",
  "params": {
    "enabled": true
  }
}
~~~

| Parameter | Type | Description |
| --- | --- | --- |
| `apiVersion` | String | The API version that was used. |
| `context` | String | The context that was used when the request was made (optional). |
| `method` | String | The method that should be used. |
| `params` | Object | Contains method specific parameters. |
| `params.enable` | Boolean | States if the compass should be enabled. `true` = enabled or `false` = disabled. |

**Response - Success**

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

```json
{
  "apiVersion": "2.0",
  "context": "example",
  "method": "setCompassState",
  "data": {}
}

Parameters	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that was performed.
`data`	Object	Contains response specific parameters.

Response - Error

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "setCompassState",
    "error": {
        "code": 2003,
        "message": "The requested API version is not supported."
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The performed method.
`error`	Object	The error object.
`error.code`	Integer	The error code.
`error.message`	String	The error message for the corresponding error code.

Error codes

See General error codes for a list of potential errors.

Use this method to list all available tags for the preset positions.

Request

curl
HTTP

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/axis-cgi/ptz-orientationaid.cgi" \
  --data '{
  "apiVersion": "2.0",
  "context": "example",
  "method": "listTags"
}'

POST /axis-cgi/ptz-orientationaid.cgi
Host: <servername>
Content-Type: application/json

{
  "apiVersion": "2.0",
  "context": "example",
  "method": "listTags"
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that should be used.

Response - Success

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "listTags",
    "data": {
        "id": "id",
        "text": "text",
        "display": true
    }
}

Parameters	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that was performed.
`data`	Object	Contains response specific parameters.
`data.id`	String	The ID of the preset position.
`data.text`	String	The name of the preset position.
`data.display`	Boolean	Indicates whether the preset position is displayed in the device web interface.

Response - Error

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "listTags",
    "error": {
        "code": 2003,
        "message": "The requested API version is not supported."
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The performed method.
`error`	Object	The error object.
`error.code`	Integer	The error code.
`error.message`	String	The error message for the corresponding error code.

Error codes

See General error codes for a list of potential errors.

setTagState

Use this method to show the tags for preset positions or not.

Request

curl
HTTP

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/axis-cgi/ptz-orientationaid.cgi" \
  --data '{
  "apiVersion": "2.0",
  "context": "example",
  "method": "setTagState",
  "params": {
    "tagList": [
      {
        "id": "id",
        "display": true
      }
    ]
  }
}'

POST /axis-cgi/ptz-orientationaid.cgi
Host: <servername>
Content-Type: application/json

{
  "apiVersion": "2.0",
  "context": "example",
  "method": "setTagState",
  "params": {
    "tagList": [
      {
        "id": "id",
        "display": true
      }
    ]
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that should be used.
`params`	Object	Contains method specific parameters.
`params.tagList`	Array	Container for the tag list.
`params.tagList.id`	String	The ID of the preset position.
`params.tagList.display`	Boolean	Indicates whether the preset position is displayed in the device web interface.

Response - Success

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "setTagState",
    "data": {}
}

Parameters	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that was performed.
`data`	Object	Contains response specific parameters.

Response - Error

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "setTagState",
    "error": {
        "code": 2003,
        "message": "The requested API version is not supported."
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The performed method.
`error`	Object	The error object.
`error.code`	Integer	The error code.
`error.message`	String	The error message for the corresponding error code.

Error codes

See General error codes for a list of potential errors.

getSupportedVersions

Use this method to get a list of API versions supported by your device.

Request

curl
HTTP

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/axis-cgi/ptz-orientationaid.cgi" \
  --data '{
  "apiVersion": "2.0",
  "context": "example",
  "method": "getSupportedVersions"
}'

POST /axis-cgi/ptz-orientationaid.cgi
Host: <servername>
Content-Type: application/json

{
  "apiVersion": "2.0",
  "context": "example",
  "method": "getSupportedVersions"
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that should be used.

Response - Success

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "getSupportedVersions",
    "data": {
        "apiVersions": ["1.0", "2.0"]
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The method that should be used.
`data`	Object	Contains response specific parameters.
`data.apiVersions`	Array	A list containing all supported major versions along with their highest minor version, e.g. `["1.0", "1.2"]`.

Return value - Failure

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

{
    "apiVersion": "2.0",
    "context": "example",
    "method": "getSupportedVersions",
    "error": {
        "code": 2003,
        "message": "The requested API version is not supported."
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	The context that was used when the request was made (optional).
`method`	String	The performed method.
`error`	Object	The error object.
`error.code`	Integer	The error code.
`error.message`	String	The error message for the corresponding error code.

Error codes

See General error codes for a list of potential errors.

General error codes

This table lists the general error codes that can occur for any API method. Method specific errors are listed under the respective descriptions.

Code	Description
`1000`	Invalid parameter value.
`2003`	The requested API version is not supported.
`2004`	Method not supported.
`4000`	The provided JSON input was invalid.
`4001`	A mandatory input parameter was not found in the input.
`4002`	The type of a provided JSON parameter was incorrect.
`8000`	Internal error, could not complete the request.
`8002`	Generic Error.

Description​

Identification​

Authorization​

Use cases​

Set north direction​

Get compass state​

Set compass state​

List tags​

Show or hide the tags for the preset positions​

API specifications​

setNorth​

getCompassState​

setCompassState​

listTags​

setTagState​

getSupportedVersions​

General error codes​

Description

Identification

Authorization

Use cases

Set north direction

Get compass state

Set compass state

List tags

Show or hide the tags for the preset positions

API specifications

setNorth

getCompassState

setCompassState

listTags

setTagState

getSupportedVersions

General error codes