PTZ Autotracker API

Description

The PTZ Autotracker API will show you the steps required to track moving objects with your Axis PTZ camera. The Autotracker itself comes pre-installed on supported cameras and the API consists of a number of CGIs used for querying status and information, and controlling the Autotracker functions, divided into the following sub-groups:

  • The general settings, including filters, GUI view settings, etc.

  • A switch with which you can turn on and off the profile tracking.

  • Functions for the metadata stream, which are also used to set the image rotation.

  • The on/off switch for the automatic profile (zone) triggers.

  • The profile (zone) configurations.

Model

The API implements the following CGIs and methods:

The PTZ Autotracker POST CGIs
CGIURLUserDescription
settings.fcgi//<servername>/local/axis-ptz-autotracking/settings.fcgiAdminChecks and changes the tracker settings.
operator.fcgi//<servername>/local/axis-ptz-autotracking/operator.fcgiOperatorChecks and changes the tracker settings.
viewer.fcgi//<servername>/local/axis-ptz-autotracking/viewer.fcgiViewerChecks the tracker settings.
The PTZ Autotracker API functions
MethodDescription
setViewportConfigConfigures the Autotracker to include the camera’s rotation setting.
getViewportConfigReturns the camera’s current rotation setting.
setAutotrackingSettingsChanges the general PTZ Autotracker settings.
getAutotrackingSettingsLists the general PTZ Autotracker settings.
setAutotrackingTargetStarts following an object visible in the video stream.
getAutotrackingTargetReturns the currently tracked object.
setAutotrackingStateEnable/disables the automatic tracking in the zones.
getAutotrackingStateReturns the state of the automatic tracking in the zones.
addProfileCreates a new profile.
updateProfileChanges the settings for an existing profile.
getProfileReturns the profile settings.
deleteProfileRemoves the profile.

Identification

Property

Properties.API.HTTP.Version=3

Firmware

9.10 and later

API Discovery

id=autotracking-2

Common examples

Get supported versions

Use this example to check which version of the PTZ Autotracker that exists for your device.

1. Request version support for the PTZ Autotracker protocol.

User level

Admin, Operator, Viewer

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getSupportedVersions",
  "params": {}
}

2. Parse the JSON response.

Successful response
{
  "apiVersion": "2.1",
  "context": "abc",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [
      "1.0",
      "2.1"
    ]
  }
}
Error response
{
  "apiVersion": "2.1",
  "context": "abc",
  "method": "getSupportedVersions",
  "error": {
    "code": 1003
  }
}

API references

See getSupportedVersions for further instructions.

Set and get the current settings

Use this example to retrieve a list of the general settings for the PTZ Autotracker.

Get settings

1. Request the current general settings for the autotracker.

User level

Admin, Operator, Viewer

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingSettings",
  "params": {}
}

2. Parse the JSON response.

Successful response
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingSettings",
  "data": {
    "minObjectSize": {
      "width": 7,
      "height": 7,
      "enabled": true
    },
    "minObjectLifespan": {
      "time": 3,
      "enabled": true
    },
    "profiles": [
      {
        "id": 1,
        "name": "Profile 1",
        "preset": -1,
        "enabled": false
      },
      {
        "id": 2,
        "name": "Profile 2",
        "preset": -1,
        "enabled": false
      },
      {
        "id": 3,
        "name": "Profile 3",
        "preset": 5,
        "enabled": false
      }
    ]
  }
}
Error response
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingSettings",
  "error": {
    "code": 1003
  }
}

API references

See getAutotrackingSettings for further instructions.

Update current settings

1. Update the autotracker settings.

User level

Admin, Operator

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingSettings",
  "params": {
    "minObjectSize": {
      "width": 3,
      "height": 3,
      "enabled": false
    }
  }
}

2. Parse the JSON response.

Successful example
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingSettings",
  "data": {
  }
}

API references

See setAutotrackingSettings for further instructions.

Set current viewport

1. Request the autotracker to send a list of potential moving objects and visible zones (profiles) in the JSON format.

User level

Admin, Operator, Viewer

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setViewportConfig",
  "params": {
    "rotation": 180
  }
}
Successful response
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setViewPortConfig",
  "data": {
  }
}

API references

See setViewportConfig and getViewportConfig for further instructions.

API specifications

getSupportedVersions

This API method retrieves a list of supported major API versions along with their highest supported minor version.

Request

User level

Admin, Operator, Viewer

Method

POST

Content-type

application/json

JSON input parameters
{
  "context": "abc",
  "method": "getSupportedVersions",
  "params": {
  }
}
ParameterTypeDescription
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "<Major2.Minor2>",
  "context": "abc",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["<Major1>.<Minor1>", "<Major2>.<Minor2>"]
  }
}
ParametersTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains response specific parameters.
apiVersionsArrayThe supported API versions presented in the format “Major.Minor”.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "Major.Minor",
  "context": "abc",
  "method": "getSupportedVersions",
  "error": {
    "code": <integer error code>
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

See General error codes for a list of potential errors.

getAutotrackingSettings

This API method lists available autotracker settings.

Request

User level

Admin, Operator, Viewer

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingSettings",
  "params": {
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in thee response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingSettings",
  "data": {
    "minObjectSize": {
      "width": 7,
      "height": 7,
      "enabled": true
    },
    "minObjectLifespan": {
      "time": 3,
      "enabled": true
    },
    "profiles": [
      {
        "id": 1,
        "name": "Profile 1",
        "preset": -1,
        "enabled": false
      },
      {
        "id": 2,
        "name": "Profile 2",
        "preset": -1,
        "enabled": false
      },
      {
        "id": 3,
        "name": "Profile 3",
        "preset": 5,
        "enabled": false
      }
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used, presented in the format Major.Minor.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains the method specific parameters listed below.
minObjectSizeObjectThe minimum size settings for an object that can be triggered in the zones.
minObjectLifespanObjectThe minimum lifespan (in seconds) for an object that can be triggered in the zones.
profilesArrayA list of available profiles (zones) along with their settings.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingSettings",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

See General error codes for a list of potential errors.

setAutotrackingSettings

This API method changes the general PTZ Autotracker settings. You will not be able change profile settings with this method and only JSON objects included in the request can be updated. So for example, if you want to remove a color combination, you need to send a JSON object with that id included.

User level

Admin, Operator

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingSettings",
  "params": {
    "minObjectSize": {
      "width": 7,
      "height": 7,
      "enabled": true
    },
    "minObjectLifespan": {
      "time": 3,
      "enabled": true
    },
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.
minObjectSizeObjectThe minimum object size that can cause a trigger in a zone.
minObjectLifespanObjectThe minimum lifespan (in seconds) for an object to cause a trigger in a zone.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingSettings",
  "data": {
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used, presented in the format “Major.Minor”.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains the method specific parameters.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingSettings",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

CodeDescription
1101Invalid profile ID
1102Max number of profiles reached
1103Invalid number of coordinates in zone (not equal x/y for example)
1104Too many coordinates in zone
1105Too few coordinates in zone
1106Profile name empty
1107Invalid preset
1108Could not update zone
1109No zone included
1201Invalid color id
1202No colours configured
1301Invalid min object size width
1302Invalid min object size height
1401Invalid lifespan time
1801Invalid value for timeout to home
1802Invalid value for zoom limit
1803Invalid value for max profile number

See General error codes for a list of potential errors.

setAutotrackingTarget

This API method starts the object tracking.

User level

Admin, Operator

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingTarget",
  "params": {
    "targetId": 101
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.
targetIdIntegerThe video-scene ID for the object that should be followed. -1 is used to stop the tracking.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingTarget",
  "data": {
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains response specific parameters.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingTarget",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

CodeDescription
1101Invalid object ID

See General error codes for a list of potential errors.

getAutotrackingTarget

This API method allows the application to operate in either manual or automatic mode. For example, if the getAutotrackingState returns enabled = true, it means that the application is in automatic mode.

Request

User level

Admin, Operator

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingTarget",
  "params": {
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingTarget",
  "data": {
    "targetId": 101
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains response specific parameters.
targetIdIntegerThe video-scene ID for the object that is followed. -1 is used for not tracking.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingState",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

CodeDescription
1101Invalid object ID

See General error codes for a list of potential errors.

setViewportConfig

This API method sets the viewport rotation. Supported rotation values are between 0 and 180 degrees.

Request

User level

Admin, Operator, Viewer

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setViewportConfig",
  "params": {
    "rotation": 180
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.
rotationIntegerRotation value of the camera. Only values between 0 and 180 are supported.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setViewportConfig",
  "data": {
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains response specific parameters.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setViewportConfig",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

CodeDescription
1101Invalid object ID

See General error codes for a list of potential errors.

getViewportConfig

This API method returns the value set by the setViewportConfig, or a negative value if nothing has been set.

Request

User level

Admin, Operator, Viewer

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getViewportConfig",
  "params": {
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getViewportConfig",
  "data": {
    "rotation": 180
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains response specific parameters.
rotationIntegerThe camera rotation. -1 will be used if rotation hasn’t been initialized, otherwise a value of either 0 or 180 will be used..

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getViewportConfig",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

CodeDescription
1101Invalid object ID

See General error codes for a list of potential errors.

Object stream description

Once a viewport has been configured, the application will start sending metadata on the camera’s event channel such as this:

<MESSAGE > ---- Event ------------------------
<MESSAGE > Global Declaration Id: 165
<MESSAGE > Local Declaration Id: 1
<MESSAGE > Producer Id: 38
<MESSAGE > Timestamp: 1549289932.405513
<MESSAGE > [jsonframe = '{"objects":[{"id":11215,"x":0.4176,"y":0.3057,"width":0.01257,"height":0.04077},{"id":11210,"x":0.3989,"y":0.239,"width":0.008301,"height":0.04822},{"id":11205,"x":0.7885,"y":0.03162,"width":0.0459,"height":0.04077}],"zones":[{"profileId":1,"zoneType":0,"polygon":[0.2888,0.3782,0.3907,0.3679,0.4277,0.4849,0.3054,0.5005]}]}'] {onvif-data}
<MESSAGE > [tnsaxis:topic0 = 'CameraApplicationPlatform']
<MESSAGE > [tnsaxis:topic2 (streamObjects) = 'streamObjects' (streamObjects)] {isApplicationData}
<MESSAGE > [tnsaxis:topic1 (PtzAutotracking) = 'PtzAutotracking' (PtzAutotracking)]

This example shows the metadata with three moving objects and one zone (with four corners) visible in the video stream. Zone coordinates may be outside the [0,1] range, as they can be outside the visible screen. All x- and y-coordinates range between 0 and 1, where [0,0] is the top left corner and [1,1] is bottom right.

{
  "object": [
    {
      "id": 11215,
      "x": 0.4176,
      "y": 0.3057,
      "width": 0.01257,
      "height": 0.04077
    },
    {
      "id": 11210,
      "x": 0.3989,
      "y": 0.239,
      "width": 0.008301,
      "height": 0.04822
    },
    {
      "id": 11205,
      "x": 0.7885,
      "y": 0.3162,
      "width": 0.0459,
      "height": 0.04077
    }
  ],
  "zones": [
    {
      "profileId": 1,
      "zoneType": 0,
      "polygon": [
        0.2888, 0.3782,
        0.3907, 0.3679,
        0.4277, 0.4849,
        0.3054, 0.5005
      ]
    }
  ]
}
ParameterTypeDescription
objectsArrayA list of moving objects visible on screen.
idIntegerThe object ID that will be used when starting manual tracking.
xDoubleThe X coordinate of the top left corner of the object.
yDoubleThe Y coordinate of the top left corner of the object.
widthDoubleThe object width.
heightDoubleThe object height.
zonesArrayA list of zones visible on screen.
profileIdIntegerThe zone ID.
zoneTypeIntegerThe zone type.
polygonArrayA list of [x,y] coordinates. Represents the corner of the profile/zone.

setAutotrackingState

This API method sets the application to either manual or automatic mode. If the autotracking state is enabled, it will be set to automatic mode and the first object that enters a zone will automatically trigger the tracking. When the autotracking is set to manual there is no automatic triggering active, which means that zones and profiles are turned off.

Request

User level

Admin, Operator

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingState",
  "params": {
    "enabled": true
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format ”Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.
enabledBooleanThe tracking option status.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingState",
  "data": {
  }
}
ParameterTypeDescription
apiVersionStringThe API that was used, presented in the format “Major.Minor”.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains method specific parameters.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setAutotrackingState",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

See General error codes for a list of potential errors.

getAutotrackingState

This API method retrieves the application in either manual or automatic mode. If getAutotrackingState returns enabled = true, it means that the application is in automatic mode.

Request

User level

Admin, Operator

Method

POST

JSON input parmeters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingState",
  "params": {
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingState",
  "data": {
    "enabled": true
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used, presented in the format “Major.Minor”.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains the method specific parameters.
enabledBooleanDetermines whether tracking is set to automatic or manual.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getAutotrackingState",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

See General error codes for a list of potential errors.

addProfile

This API method adds a profile to the PTZ Autotracker settings.

Request

User level

Admin, Operator

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "addProfile",
  "params": {
    "name": "Profile 1",
    "preset": -1,
    "enabled": false,
    "polygon": [
      0.426,
      0.574,
      0.326,
      0.774,
      0.526,
      0.774
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.
nameStringThe profile name.
presetIntegerThe number of connected presets. -1 if no preset is connected.
enabledBooleanTrue if a profile/zone is enabled.
polygonArrayAn array containing the floats, such as a three point polygon ([x[0], y[0], x[1], y[1], x[2], y[2]]).

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "addProfile",
  "data": {
    "id": 1
    "name": "Profile 1",
    "preset": -1,
    "enabled": false
  }
}
ParameterTypeDescription
apiVersionStringThe API that was used, presented in the format “Major.Minor”.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains method specific parameters.
idIntegerThe profile ID.
nameStringThe profile name.
presetIntegerThe number of connected presets. -1 if no preset is connected.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "addProfile",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

CodeDescription
1102Max number of profiles reached
1103Invalid number of coordinates in zone (not equal x/y for example)
1104Too many coordinates in zone
1105Too few coordinates in zone
1109No zone included

See General error codes for a list of potential errors.

getProfile

This API method fetches all settings associated with a profile.

Request

User level

Admin, Operator, Viewer

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getProfile",
  "params": {
    "id": 1
  }
}
ParameterTypeDescription
apiVersionStringThe requested API in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.
idIntegerThe ID for the requested profile.

Response value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getProfile",
  "data": {
    "id": 1,
    "name": "Profile 1",
    "preset": -1,
    "enabled": false,
    "polygon": [
      0.426,
      0.574,
      0.326,
      0.774,
      0.526,
      0.774
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe API that was used, presented in the format “Major.Minor”.
contextStringA text string that will be echoed back as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains method specific parameters.
idIntegerThe profile ID.
nameStringThe profile name.
presetIntegerThe number of connected presets. -1 if no preset is connected.
enabledBooleanSet to true if this profile/zone has been enabled.
polygonArrayAn array containing floats, such as a three point polygon ([x[0], y[0], x[1], y[1], x[2], y[2]]).

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getProfile",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

See General error codes for a list of potential errors.

updateProfile

This API method updates the PTZ Autotracker profile settings. As with other interfaces, the JSON objects sent are the ones that will be updated, for example, if only id and name are included in the request, only those will be updated, while polygon and other settings will remain unchanged.

The polygon array is a list of x and y coordinates that corresponds to the corners of the polygon (between 3 and 10 corners) currently shown by the video stream on the camera.

Request

User level

Admin, Operator

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "updateProfile",
  "params": {
    "id": 1,
    "name": "Profile 1",
    "preset": -1,
    "enabled": false,
    "polygon": [
      0.426,
      0.574,
      0.326,
      0.774,
      0.526,
      0.774
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe requested API in the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.
idIntegerThe ID of the requested profile.
nameStringThe profile name.
presetIntegerThe number of connected presets. -1 if no preset is connected.
enabledBooleanTrue if a profile/zone is enabled.
polygonArrayAn array containing the floats, such as a three point polygon ([x[0], y[0], x[1], y[1], x[2], y[2]]).

Response value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "updateProfile",
  "data": {
    "id": 1,
    "name": "Profile 1",
    "preset": -1,
    "enabled": false
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used, presented in the format “Major.Minor”.
contextStringA text string that will be echoed back as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains method specific parameters.
idIntegerThe profile ID.
nameStringThe profile name.
presetIntegerThe number of connected presets. -1 if no preset is connected.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "updateProfile",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

CodeDescription
1103Invalid number of coordinates in zone (not equal x/y for example)
1104Too many coordinates in zone
1105Too few coordinates in zone

See General error codes for a list of potential errors.

deleteProfile

This API method deletes a PTZ Autotracker profile.

Request

User level

Admin, Operator

Method

POST

JSON input parameters
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "deleteProfile",
  "params": {
    "id": 1
  }
}
ParameterTypeDescription
apiVersionStringThe requested API version the format “Major.Minor”.
contextStringThe user sets this value and the application echoes it back in the response (optional).
methodStringThe method that should be used.
paramsObjectContains method specific parameters.
idIntegerThe ID of the requested profile.

Response value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "deleteProfile",
  "data": {
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe method that was performed.
dataObjectContains method specific parameters.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "deleteProfile",
  "error": {
    "code": 1003
  }
}
ParameterTypeDescription
apiVersionStringThe API version that was used.
contextStringA text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
methodStringThe performed method.
codeIntegerThe error code.

Error codes

CodeDescription
1101Invalid profile ID

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.

CodeDescription
1001The provided JSON input was invalid.
1002No Method name tag found in request.
1003Method not supported.
1004Parameter tag (”params”) required, but missing.
1005Required parameter missing.
1006Invalid value of parameter.
1007Internal error.