PTZ Autotracker API

Description

The PTZ Autotracker API will show you the steps required to track moving objects with your Axis PTZ camera. 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

URL	User	Description
`http://<servername>/axis-cgi/ptz-autotracking/admin.cgi`	Admin	Configure all tracker settings.
`http://<servername>/axis-cgi/ptz-autotracking/operator.cgi`	Operator	Checks and changes the tracker settings for the operator.
`http://<servername>/axis-cgi/ptz-autotracking/viewer.cgi`	Viewer	Checks the tracker settings.

note

URLs starting with /local/ and ending with .fcgi are deprecated and will be removed in a future LTS release.

The PTZ Autotracker API functions

Method	Description
`getSupportedVersions`	Lists the supported API versions.
`setViewportConfig`	Configures the autotracker to include the camera's rotation setting.
`getViewportConfig`	Returns the current rotation setting of the camera.
`getApplicationSettings`	Returns the general application settings.
`setApplicationSettings`	Sets the general application settings.
`getAutotrackingSettings`	Lists the general autotracking settings.
`setAutotrackingSettings`	Changes the general autotracking settings.
`getAutotrackingTarget`	Returns the currently tracked object. -1 if not tracking.
`setAutotrackingTarget`	Starts or stops following an object visible in the video stream. Positive value to start, -1 to stop.
`getAutotrackingState`	Returns the state of the automatic triggering in zones.
`setAutotrackingState`	Enables/disables automatic triggering in zones.
`addProfile`	Creates a new profile.
`getProfile`	Returns the settings for a profile.
`updateProfile`	Changes the settings of an existing profile.
`deleteProfile`	Removes the profile.
`setTempZone`	Creates a temporary zone for automatic detection and tracking.
`getRadarAutotrackingSettings`	Lists the general radar autotracker settings.
`setRadarAutotrackingSettings`	Changes the general radar autotracking settings.
`getRadarAutotrackingCapabilities`	Lists the general radar autotracker capabilities.
`addRadarProfile`	Creates a new radar profile.
`getRadarProfile`	Returns the settings for a radar profile.
`updateRadarProfile`	Changes the settings of an existing radar profile.
`deleteRadarProfile`	Removes the radar profile.
`sendTestAutotrackingEvent`	Temporarily trigger an autotracking event to the event server.

Identification

Property: Properties.API.HTTP.Version=3
AXIS OS: 9.10 and later
API Discovery: id=autotracking-2

Version history

Version 1.0

The following parameters are added:

timeoutToHome
aoaId
trackingParams
zoomLimitHigh
zoomLimitLow
maxProfileNumber
trackerType
returnToPreset
maxTrackingTime
zoneType
maxObjectSpeed
minObjectSizeDegrees
svgFrameColours
trackerSupport
apiSupport/aoa
apiSupport/radar

Authentication

For detailed information on how to authenticate requests to this API, please refer to Authentication.

Use cases

Get supported versions

Use this example to check which versions of the PTZ Autotracker protocol your device supports.

Request PTZ Autotracker protocol version support.

User level: Admin, Operator, Viewer

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getSupportedVersions",
    "params": {}
}

Parse the JSON response.

Successful response

{
    "apiVersion": "1.8",
    "context": "abc",
    "method": "getSupportedVersions",
    "data": {
        "apiVersions": ["1.8"]
    }
}

Error response

{
    "apiVersion": "1.8",
    "context": "abc",
    "method": "getSupportedVersions",
    "error": {
        "code": 1003
    }
}

Get settings

Use this example to retrieve the current general settings for the PTZ Autotracker.

Request the current general settings.

User level: Admin, Operator, Viewer

JSON input parameters

{
    "context": "abc",
    "apiVersion": "1",
    "method": "getAutotrackingSettings",
    "params": {}
}

Parse the JSON response.

Successful response

{
    "context": "abc",
    "apiVersion": "1.8",
    "method": "getAutotrackingSettings",
    "data": {
        "minObjectSize": {
            "width": 7,
            "height": 7,
            "enabled": true
        },
        "minObjectLifespan": {
            "time": 3,
            "enabled": true
        },
        "trackingParams": {
            "timeoutToHome": 5,
            "zoomLimit": 8,
            "maxProfileNumber": 10
        },
        "svgFrameColours": {
            "colourCombinations": [
                {
                    "id": 1,
                    "tracked": "#ed1a3b",
                    "default": "#8dc63f"
                },
                {
                    "id": 2,
                    "tracked": "#ffc300",
                    "default": "#3dc8ff"
                },
                {
                    "id": 3,
                    "tracked": "#ed1a3b",
                    "default": "#3dc8ff"
                }
            ],
            "activeId": 3,
            "highlightObjects": false
        },
        "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

{
    "context": "abc",
    "apiVersion": "1.8",
    "method": "getAutotrackingSettings",
    "error": {
        "code": 1003
    }
}

Update current settings

Use this example to update settings in the PTZ Autotracker. Include only the settings you want to change.

Send the updated settings.

User level: Admin, Operator

JSON input parameters

{
    "context": "abc",
    "apiVersion": "1",
    "method": "setAutotrackingSettings",
    "params": {
        "minObjectSize": {
            "width": 3,
            "height": 3,
            "enabled": false
        }
    }
}

Parse the JSON response.

Successful response

{
    "context": "abc",
    "apiVersion": "1.8",
    "method": "setAutotrackingSettings",
    "data": {}
}

Set current viewport

Use this example to request the PTZ Autotracker to start sending its list of moving objects and visible zones in JSON format.

Set the viewport configuration.

User level: Admin, Operator, Viewer

JSON input parameters

{
    "context": "abc",
    "apiVersion": "1",
    "method": "setViewportConfig",
    "params": {
        "rotation": 180
    }
}

Parse the JSON response.

Successful response

{
    "context": "abc",
    "apiVersion": "1.8",
    "method": "setViewportConfig",
    "data": {}
}

Get radar autotracking settings

Use this example to retrieve the current radar autotracker settings.

Request the current radar autotracking settings.

User level: Admin, Operator, Viewer

JSON input parameters

{
    "apiVersion": "1",
    "method": "getRadarAutotrackingSettings",
    "params": {}
}

Parse the JSON response.

Successful response

{
    "apiVersion": "1.8",
    "method": "getRadarAutotrackingSettings",
    "data": {
        "radarPTZAlignment": {
            "radarPanOffset": 0.0
        },
        "radarProfiles": [
            {
                "id": 1,
                "radarScenarioUuid": "550e8400-e29b-41d4-a716-446655440000",
                "name": "Profile 1",
                "enabled": true,
                "priority": 1,
                "videoObjectClassifications": ["car", "human"],
                "trackingRequirement": "requireRadarTrack",
                "vodConfirmationTime": 5.0
            }
        ],
        "objectPriority": {
            "usedPriority": "periodic",
            "periodicTimeSeconds": 20.0
        }
    }
}

Error response

{
    "apiVersion": "1.8",
    "method": "getRadarAutotrackingSettings",
    "error": {
        "code": 1003
    }
}

Get radar autotracking capabilities

Use this example to retrieve the current radar autotracker capabilities.

Request the radar autotracking capabilities.

User level: Admin, Operator, Viewer

JSON input parameters

{
    "apiVersion": "1",
    "method": "getRadarAutotrackingCapabilities",
    "params": {}
}

Parse the JSON response.

Successful response

{
    "apiVersion": "1.8",
    "method": "getRadarAutotrackingCapabilities",
    "data": {
        "radarPTZAlignment": {
            "radarPanOffset": {
                "min": -180.0,
                "max": 180.0
            }
        },
        "objectPriority": {
            "objectPriorities": ["first", "last", "periodic", "closest", "furthest", "slowest", "fastest"],
            "periodicTimeSeconds": {
                "min": 0.1
            }
        },
        "radarProfiles": {
            "priority": {
                "min": 1,
                "max": 20
            },
            "videoObjectClassifications": ["human", "bus", "car", "truck", "motorcycle_bicycle", "vehicle_other"],
            "trackingRequirements": ["requireRadarTrigger", "requireRadarTrack", "requireAny"],
            "vodConfirmationTime": {
                "min": 5.0,
                "default": 5.0,
                "max": 15.0
            }
        }
    }
}

Update current radar settings

Use this example to update the radar autotracker settings. Include only the settings you want to change.

Send the updated radar settings.

User level: Admin, Operator

JSON input parameters

{
    "apiVersion": "1",
    "method": "setRadarAutotrackingSettings",
    "params": {
        "radarPTZAlignment": {
            "radarPanOffset": 60.0
        }
    }
}

Parse the JSON response.

Successful response

{
    "apiVersion": "1.8",
    "method": "setRadarAutotrackingSettings",
    "data": {}
}

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

{ "apiVersion": "1", "context": "abc", "method": "getSupportedVersions", "params": {} }

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The method that should be used.
`params`	Object	Contains 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>"]
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	A text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
`method`	String	The method that was performed.
`data`	Object	Contains response specific parameters.
`apiVersions`	Array	The 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>
  }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	A text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
`method`	String	The performed method.
`code`	Integer	The error code.

Error codes

See General error codes for a list of potential errors.

getApplicationSettings

This API method lists the current application settings.

Request

User level: Admin, Operator, Viewer
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getApplicationSettings",
    "params": {}
}

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getApplicationSettings",
    "data": {
        "service": {
            "active": true,
            "version": "2.6.125"
        },
        "apiSupport": {
            "aoa": true,
            "radar": true
        }
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.
`service`	Object	Application service settings.
`active`	Boolean	Whether the autotracking service is active.
`version`	String	Optional. The version of the service.
`apiSupport`	Object	Optional. Supported APIs.
`aoa`	Boolean	Optional. Whether the AOA API is supported.
`radar`	Boolean	Optional. Whether the radar API is supported.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getApplicationSettings",
    "error": {
        "code": 1003
    }
}

setApplicationSettings

Application settings control the PTZ Autotracker service. They indicate whether the Autotracking service is running or not.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setApplicationSettings",
    "params": {
        "service": {
            "active": true
        }
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below. You must include at least one of the parameters below.
`service`	Object	Container for active state.
`active`	Boolean	Determines whether the application subscribes to data sources and stays active.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setApplicationSettings",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setApplicationSettings",
    "error": {
        "code": 1003
    }
}

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
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingSettings",
    "params": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The method that should be used.
`params`	Object	Contains method specific parameters.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingSettings",
    "data": {
        "minObjectSize": {
            "width": 7,
            "height": 7,
            "enabled": true
        },
        "minObjectLifespan": {
            "time": 3,
            "enabled": true
        },
        "trackerSupport": {
            "supported": [
                {
                    "trackerId": 0,
                    "trackerName": "MOTE"
                },
                {
                    "trackerId": 5,
                    "trackerName": "VOD2"
                },
                {
                    "trackerId": 6,
                    "trackerName": "RadarFusion"
                }
            ],
            "activeTrackerId": 5
        },
        "trackingParams": {
            "timeoutToHome": 5.0,
            "zoomLimitHigh": 8.0,
            "zoomLimitLow": 1.0,
            "maxProfileNumber": 10,
            "trackerType": 5,
            "returnToPreset": -1,
            "maxTrackingTime": 0
        },
        "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
            }
        ]
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.
`minObjectSize`	Object	Minimum object size settings, in percentage of the screen, for triggering in zones.
`minObjectLifespan`	Object	Minimum object lifespan in seconds for triggering in zones.
`trackerSupport`	Object	Optional. Lists available tracker types and may change the active type. Listed in the trackerSupport table.
`trackingParams`	Object	Optional. Object holding various tracker related settings. Listed in the trackingParams table.
`profiles`	Array	Array of profiles (aka zones) with some related settings.

trackingParams parameters

Parameter	Type	Description
`timeoutToHome`	Number	Time in seconds the tracker waits after losing an object before returning to preset. This is the global setting, but you can override it locally by setting timeoutToHome in a profile.
`zoomLimitHigh`	Number	Maximum zoom in magnification. Should be 1.0 or higher.
`zoomLimitLow`	Number	Minimum zoom in magnification. Should be 1.0 or higher.
`maxProfileNumber`	Integer	The maximum number of profiles you can create.
`trackerType`	Integer	The data source the tracker uses. 0 - MOTE, 5 - VOD++, 6 - Radar.
`returnToPreset`	Integer	Preset to return to after a click-to-track action has finished. If set to -1, home preset will be used.
`maxTrackingTime`	Integer	The maximum time in seconds an object is tracked before returning to preset. If set to 0, the object is tracked indefinitely.

trackerSupport parameters

Parameter	Type	Description
`supported`	Array	List of objects containing trackerId and trackerName for each supported tracker type.
`activeTrackerId`	Integer	Currently active trackerId.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingSettings",
    "error": {
        "code": 1003
    }
}

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 to 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.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingSettings",
    "params": {
        "minObjectSize": {
            "width": 7,
            "height": 7,
            "enabled": true
        },
        "minObjectLifespan": {
            "time": 3,
            "enabled": true
        },
        "trackerSupport": {
            "activeTrackerId": 5
        },
        "trackingParams": {
            "timeoutToHome": 5.0,
            "zoomLimitHigh": 8.0,
            "zoomLimitLow": 1.0,
            "maxProfileNumber": 10,
            "trackerType": 5,
            "returnToPreset": -1,
            "maxTrackingTime": 0
        }
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below. You must include at least one of the parameters below.
`minObjectSize`	Object	Optional. Minimum object size settings, in percentage of the screen, for triggering in zones.
`minObjectLifespan`	Object	Optional. Minimum object lifespan in seconds for triggering in zones.
`trackerSupport`	Object	Optional. Use this to change the active trackerId. However, the list of supported trackers is read-only and cannot be changed.
`trackingParams`	Object	Optional. Contains various tracker-related settings. Listed in the trackingParams table.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingSettings",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used, presented in the format "Major".
`context`	String	A text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
`method`	String	The method that was performed.
`data`	Object	Contains the method specific parameters.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingSettings",
    "error": {
        "code": 1003
    }
}

Parameter	Type	Description
`apiVersion`	String	The API version that was used.
`context`	String	A text string that will be echoed back as long as it was provided by the user in the corresponding request (optional).
`method`	String	The performed method.
`code`	Integer	The error code.

Error codes

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

See General error codes for a list of potential errors.

Get and set viewport configuration (rotation)

Use this to set the viewport rotation the backend uses. Supported rotation settings are only 0 and 180 degrees. The backend doesn't stream object data until you call this function.

note

If two different frontends set different rotation settings, the backend behaviour is unspecified.

getViewportConfig

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

Request

User level: Admin, Operator, Viewer
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getViewportConfig",
    "params": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getViewportConfig",
    "data": {
        "rotation": 180
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.
`rotation`	Integer	Mandatory. Rotation of camera. -1 if not initialized. 0 or 180 otherwise.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getViewportConfig",
    "error": {
        "code": 1003
    }
}

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
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setViewportConfig",
    "params": {
        "rotation": 180,
        "metadata": true
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.
`rotation`	Integer	Mandatory. Rotation of camera. Only 0 and 180 supported.
`metadata`	Boolean	Optional, default true. Whether metadata should be enabled or not.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setViewportConfig",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setViewportConfig",
    "error": {
        "code": 1003
    }
}

Error codes

Code	Description
`1101`	Unsupported rotation value

See General error codes for a list of potential errors.

getAutotrackingTarget

This API method returns the ID of the currently tracked object.

Request

User level: Admin, Operator, Viewer
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingTarget",
    "params": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The method that should be used.
`params`	Object	Contains method specific parameters.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingTarget",
    "data": {
        "targetId": 101
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.
`targetId`	Integer	Mandatory. Object ID of object to follow. -1 for not tracking.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingTarget",
    "error": {
        "code": 1003
    }
}

setAutotrackingTarget

This API method starts the object tracking.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingTarget",
    "params": {
        "targetId": 101
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.
`targetId`	Integer	Mandatory. Object ID of object to follow. -1 to stop tracking.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingTarget",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingTarget",
    "error": {
        "code": 1003
    }
}

Error codes

Code	Description
`1101`	Invalid object ID

See General error codes for a list of potential errors.

getAutotrackingState

The PTZ Autotracking service can operate in either manual or automatic mode. When getAutotrackingState returns enabled = true, it's in automatic mode.

Request

User level: Admin, Operator, Viewer
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingState",
    "params": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingState",
    "data": {
        "enabled": true
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.
`enabled`	Boolean	Whether automatic triggering in zones is enabled.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getAutotrackingState",
    "error": {
        "code": 1003
    }
}

Error codes

See General error codes for a list of potential errors.

setAutotrackingState

The PTZ Autotracking service can operate in either manual or automatic mode. When the autotracking state is enabled it is set in automatic mode, and the first object entering a visible zone will automatically trigger the tracking. When it is set in manual mode, an external client must call the setAutotrackingTarget method to start the tracking of an object.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingState",
    "params": {
        "enabled": true
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.
`enabled`	Boolean	Mandatory. Whether tracking is enabled or disabled.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingState",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setAutotrackingState",
    "error": {
        "code": 1003
    }
}

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
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "addProfile",
    "params": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.
`name`	String	Optional. Name of the profile.
`preset`	Integer	Mandatory. Number of connected preset. -1 if no preset connected.
`enabled`	Boolean	Optional. True if this profile / zone is enabled. Default True.
`timeoutToHome`	Integer	Optional. How long tracker should wait (in seconds) after losing an object before returning to preset. This is the local setting which overrides the global setting timeoutToHome that can be set with setAutotrackingSettings. Default value is -1 which means the global setting is used.
`aoaId`	String	Conditional. Either aoaId or px_polygon is required. Id of a AOA scenario to be used for triggering tracking.
`px_polygon`	Array	Conditional. Either aoaId or px_polygon is required. Array of floats corresponding to the current position of the polygon in the current video viewport. `[x[0],y[0],x[1],y[1],x[2],y[2]]` for a three point polygon for example. Max ten points in a polygon for now.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "addProfile",
    "data": {
        "id": 1
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.
`id`	Integer	ID of the profile.
`name`	String	Optional. Name of the profile.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "addProfile",
    "error": {
        "code": 1102
    }
}

Error codes

Code	Description
`1102`	Max number of profiles reached
`1103`	Invalid number of coordinates in zone (not equal x/y for example)
`1104`	Too many coordinates in zone
`1105`	Too few coordinates in zone

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
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getProfile",
    "params": {
        "id": 1
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	The user sets this value and the application echoes it back in the response (optional).
`method`	String	The method that should be used.
`params`	Object	Contains method specific parameters.
`id`	Integer	The ID for the requested profile.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getProfile",
    "data": {
        "id": 1,
        "name": "Profile 1",
        "preset": -1,
        "enabled": false,
        "px_polygon": [0.426, 0.574, 0.326, 0.774, 0.526, 0.774]
    }
}

Parameter	Type	Description
`apiVersion`	String	The API that was used, presented in the format "Major.Minor".
`context`	String	A text string that will be echoed back as it was provided by the user in the corresponding request (optional).
`method`	String	The method that was performed.
`data`	Object	Contains method specific parameters.
`id`	Integer	The profile ID.
`name`	String	The profile name.
`preset`	Integer	The number of connected presets. `-1` if no preset is connected.
`enabled`	Boolean	Set to true if this profile/zone has been enabled.
`zoneType`	Integer	Optional. The zone type.
`timeoutToHome`	Integer	Optional. How long tracker should wait (in seconds) after losing an object before returning to preset.
`aoaId`	String	Conditional. Either aoaId or px_polygon is required. ID of an AOA scenario used for triggering tracking.
`px_polygon`	Array	Conditional. Either aoaId or px_polygon is required. Array of floats corresponding to the current position of the polygon in the current video viewport.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "getProfile",
    "error": {
        "code": 1001
    }
}

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
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "updateProfile",
    "params": {
        "id": 1,
        "name": "Profile 1",
        "preset": -1,
        "enabled": false,
        "px_polygon": [0.426, 0.574, 0.326, 0.774, 0.526, 0.774]
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.
`id`	Integer	Mandatory. ID of the profile.
`name`	String	Optional. Name of the profile.
`preset`	Integer	Optional. Number of connected preset. -1 if no preset connected.
`enabled`	Boolean	Optional. True if this profile / zone is enabled.
`timeoutToHome`	Integer	Optional. How long tracker should wait (in seconds) after losing an object before returning to preset. This is the local setting which overrides the global setting timeoutToHome that can be set with setAutotrackingSettings.
`aoaId`	String	Conditional. Either aoaId or px_polygon is required. ID of a AOA scenario to be used for triggering tracking.
`px_polygon`	Array	Conditional. Either aoaId or px_polygon is required. Array of floats corresponding to the current position of the polygon in the current video viewport. `[x[0],y[0],x[1],y[1],x[2],y[2]]` for a three point polygon for example. Max ten points in a polygon.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "updateProfile",
    "data": {
        "id": 1,
        "name": "Profile 1",
        "preset": -1,
        "enabled": false
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.
`id`	Integer	Optional. ID of the profile.
`name`	String	Optional. Name of the profile.
`preset`	Integer	Optional. Number of connected preset. -1 if no preset connected.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "updateProfile",
    "error": {
        "code": 1101
    }
}

There are no specific error codes for this method. See General error codes for a list of potential errors. Possible return codes: 1101, 1103, 1104, 1105, 1109.

deleteProfile

This API method deletes a PTZ Autotracker profile.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "deleteProfile",
    "params": {
        "id": 1
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.
`id`	Integer	Mandatory. ID of profile to be deleted.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "deleteProfile",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "deleteProfile",
    "error": {
        "code": 1101
    }
}

There are no specific error codes for this method. See General error codes for a list of potential errors. Possible return codes: 1101.

setTempZone

Create a temporary zone for automatic detection and tracking.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setTempZone",
    "params": {
        "zoneType": "fullscreen",
        "timeout": 15
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method specific parameters listed below.
`zoneType`	String	Optional. Defaults to "fullscreen".
`timeout`	Integer	Optional. Decides how long the zone will exist. Range 5..120s. Defaults to 30s.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setTempZone",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`context`	String	Optional context string. Client sets this value and the CGI echoes it back in the response.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "context": "abc",
    "method": "setTempZone",
    "error": {
        "code": 1006
    }
}

There are no specific error codes for this method. See General error codes for a list of potential errors. Possible return codes: 1006.

getRadarAutotrackingSettings

Get the current radar autotracker settings.

Request

User level: Admin, Operator, Viewer
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "method": "getRadarAutotrackingSettings",
    "params": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`params`	Object	Container for the method specific parameters listed below.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "method": "getRadarAutotrackingSettings",
    "data": {
        "radarPTZAlignment": {
            "radarPanOffset": 0.0
        },
        "radarProfiles": [
            {
                "id": 1,
                "radarScenarioUuid": "550e8400-e29b-41d4-a716-446655440000",
                "name": "Profile 1",
                "enabled": true,
                "priority": 1,
                "videoObjectClassifications": ["car", "human"],
                "trackingRequirement": "requireRadarTrack",
                "vodConfirmationTime": 5.0
            }
        ],
        "objectPriority": {
            "usedPriority": "periodic",
            "periodicTimeSeconds": 20.0
        }
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`data`	Object	Container for the method specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "method": "getRadarAutotrackingSettings",
    "error": {
        "code": 1003
    }
}

See General error codes for a list of potential errors.

setRadarAutotrackingSettings

Use this method to change the general radar autotracker settings. The API only updates the JSON objects you include in the request. Omitted objects keep their previous settings.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "method": "setRadarAutotrackingSettings",
    "params": {
        "radarPTZAlignment": {
            "radarPanOffset": 0.0
        },
        "radarProfiles": [
            {
                "radarScenarioUuid": "550e8400-e29b-41d4-a716-446655440000",
                "name": "Profile 1",
                "enabled": true,
                "priority": 1,
                "videoObjectClassifications": ["car", "human"],
                "trackingRequirement": "requireRadarTrack",
                "vodConfirmationTime": 5.0
            }
        ],
        "objectPriority": {
            "usedPriority": "periodic",
            "periodicTimeSeconds": 20.0
        }
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method-specific parameters listed below. You must include at least one of the parameters below.
`radarPTZAlignment`	Object	Optional. Number of degrees in different coordinates to align the radar and PTZ.
`radarProfiles`	Object	Optional. Radar profile options, including the profile ID, priority, video object classes to trigger on, and whether to enable tracking outside a zone.
`objectPriority`	Object	Optional. Object priority setting for when there are multiple objects. Supported values: `"first"`, `"last"`, `"periodic"`, `"closest"`, `"furthest"`, `"slowest"`, `"fastest"`. When using `"periodic"`, you can optionally set `periodicTimeSeconds`.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "method": "setRadarAutotrackingSettings",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`data`	Object	Container for the method-specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "method": "setRadarAutotrackingSettings",
    "error": {
        "code": 1003
    }
}

See General error codes for a list of potential errors.

getRadarAutotrackingCapabilities

Get the current radar autotracker capabilities.

Request

User level: Admin, Operator, Viewer
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "method": "getRadarAutotrackingCapabilities",
    "params": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`params`	Object	Container for the method-specific parameters listed below.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "method": "getRadarAutotrackingCapabilities",
    "data": {
        "radarPTZAlignment": {
            "radarPanOffset": {
                "min": -180.0,
                "max": 180.0
            }
        },
        "objectPriority": {
            "objectPriorities": ["first", "last", "periodic", "closest", "furthest", "slowest", "fastest"],
            "periodicTimeSeconds": {
                "min": 0.1
            }
        },
        "radarProfiles": {
            "priority": {
                "min": 1,
                "max": 20
            },
            "videoObjectClassifications": ["human", "bus", "car", "truck", "motorcycle_bicycle", "vehicle_other"],
            "trackingRequirements": ["requireRadarTrigger", "requireRadarTrack", "requireAny"],
            "vodConfirmationTime": {
                "min": 5.0,
                "default": 5.0,
                "max": 15.0
            }
        }
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`data`	Object	Container for the method-specific parameters listed below.
`radarPTZAlignment`	Object	Valid range for each alignment parameter.
`objectPriority`	Object	Available object priority settings and their limits.
`radarProfiles`	Object	Valid ranges and allowed values for profile parameters.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "method": "getRadarAutotrackingCapabilities",
    "error": {
        "code": 1003
    }
}

See General error codes for a list of potential errors.

addRadarProfile

Use this method to add a radar profile to the radar autotracker settings. The Autotracker service must be active to add profiles. Adding a profile fails if one with the same radarScenarioUuid already exists. The radarScenarioUuid is a unique identifier for a radar scenario, configured in the Radar Configuration CGI. You are responsible for keeping radar profiles updated if the UUIDs are changed or removed from the Radar Configuration.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "method": "addRadarProfile",
    "params": {
        "radarScenarioUuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Profile 1",
        "enabled": true,
        "priority": 1,
        "videoObjectClassifications": ["car", "human"],
        "trackingRequirement": "requireRadarTrack",
        "vodConfirmationTime": 5.0
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method-specific parameters listed below.
`radarScenarioUuid`	String	Mandatory. Unique ID of the corresponding radar scenario.
`name`	String	Mandatory. Name of the profile.
`enabled`	Boolean	Mandatory. Whether the profile should be enabled.
`priority`	Integer	Mandatory. Priority of the profile.
`videoObjectClassifications`	Array	Mandatory. Array of object types to track.
`trackingRequirement`	String	Mandatory. Strategy for how to track an object.
`vodConfirmationTime`	Number	Optional. Time in seconds allowed for VOD confirmation of a radar track before blocking the track.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "method": "addRadarProfile",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`data`	Object	Container for the method-specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "method": "addRadarProfile",
    "error": {
        "code": 1006
    }
}

See General error codes for a list of potential errors.

getRadarProfile

Get the settings for a radar profile.

Request

User level: Admin, Operator, Viewer
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "method": "getRadarProfile",
    "params": {
        "id": 1
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method-specific parameters listed below.
`id`	Integer	Mandatory. ID of the requested profile.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "method": "getRadarProfile",
    "data": {
        "id": 1,
        "radarScenarioUuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Profile 1",
        "enabled": true,
        "priority": 1,
        "videoObjectClassifications": ["car", "human"],
        "trackingRequirement": "requireRadarTrack",
        "vodConfirmationTime": 5.0
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`data`	Object	Container for the method-specific parameters listed below.
`id`	Integer	ID of the requested profile.
`radarScenarioUuid`	String	Unique ID of the corresponding radar scenario.
`name`	String	Name of the profile.
`enabled`	Boolean	Whether the profile is enabled.
`priority`	Integer	Priority of the radar profile.
`videoObjectClassifications`	Array	Array of object types to track.
`trackingRequirement`	String	Strategy for how to track an object.
`vodConfirmationTime`	Number	Time in seconds allowed for VOD confirmation of a radar track before blocking the track.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "method": "getRadarProfile",
    "error": {
        "code": 1006
    }
}

See General error codes for a list of potential errors.

updateRadarProfile

Use this method to update the radar autotracker profile settings. The API only updates the JSON objects you include in the request. For example, if you include only radarScenarioUuid and priority, the priority is updated but the video object classes and other settings remain unchanged.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "method": "updateRadarProfile",
    "params": {
        "id": 1,
        "radarScenarioUuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Profile 1",
        "enabled": true,
        "priority": 1,
        "videoObjectClassifications": ["car", "human"],
        "trackingRequirement": "requireRadarTrack",
        "vodConfirmationTime": 5.0
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method-specific parameters listed below.
`id`	Integer	Mandatory. ID of the profile to update.
`radarScenarioUuid`	String	Optional. New unique ID of the corresponding radar scenario.
`name`	String	Optional. New name of the profile.
`enabled`	Boolean	Optional. Whether the profile should be enabled.
`priority`	Integer	Optional. New priority of the radar profile.
`videoObjectClassifications`	Array	Optional. New array of object types to track.
`trackingRequirement`	String	Optional. New strategy for how to track an object.
`vodConfirmationTime`	Number	Optional. Time in seconds allowed for VOD confirmation of a radar track before blocking the track.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "method": "updateRadarProfile",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`data`	Object	Container for the method-specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "method": "updateRadarProfile",
    "error": {
        "code": 1006
    }
}

See General error codes for a list of potential errors.

deleteRadarProfile

Use this method to delete a radar profile.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "method": "deleteRadarProfile",
    "params": {
        "id": 1
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method-specific parameters listed below.
`id`	Integer	Mandatory. ID of the profile to delete.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "method": "deleteRadarProfile",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`data`	Object	Container for the method-specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "method": "deleteRadarProfile",
    "error": {
        "code": 1006
    }
}

See General error codes for a list of potential errors.

sendTestAutotrackingEvent

Use this method to test event triggering for a short period of time. The service must be active to send events.

Event types:

0: Triggers the global autotracking state event.
1: Triggers an autotracking profile event. Depending on the active tracker type, set profileId to one of the currently active profiles to trigger the corresponding event.

Request

User level: Admin, Operator
Method: POST
Content-Type: application/json

JSON input parameters

{
    "apiVersion": "1",
    "method": "sendTestAutotrackingEvent",
    "params": {
        "eventType": 0,
        "profileId": 1
    }
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`params`	Object	Mandatory. Container for the method-specific parameters listed below.
`eventType`	Integer	Mandatory. The event type to trigger (`0` or `1`).
`profileId`	Integer	Optional. Unique ID of the autotracking profile to trigger. Required if `eventType` is greater than `0`.

Return value - Success

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

Response body syntax

{
    "apiVersion": "1",
    "method": "sendTestAutotrackingEvent",
    "data": {}
}

Parameter	Type	Description
`apiVersion`	String	The requested major API version.
`method`	String	The operation to perform.
`data`	Object	Container for the method-specific parameters listed below.

Return value - Failure

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

Response body syntax

{
    "apiVersion": "1",
    "method": "sendTestAutotrackingEvent",
    "error": {
        "code": 1006
    }
}

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
`1001`	The provided JSON input was invalid.
`1002`	No Method name tag found in request.
`1003`	Method not supported.
`1004`	Parameter tag ("params") required, but missing.
`1005`	Required parameter missing.
`1006`	Invalid value of parameter.
`1007`	Internal error.

Events

Object stream description

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

objectStream event

{
    "name": "tnsaxis:CameraApplicationPlatform/tnsaxis:PtzAutotracking/tnsaxis:streamObjects",
    "niceName": "PtzAutotracking/streamObjects",
    "tags": {
        "isApplicationData": true,
        "isDeprecated": false
    },
    "availability": "Since AT 2.0"
}

objectStream event parameters

Parameter	Type	Description
`objects`	Array	List of objects visible on screen.
`zones`	Array	List of zones visible on screen.
`trackerEnabled`	Boolean	Indicates whether automatic triggers are enabled.
`trackedId`	Integer	ID of the tracked object. Optional.
`isMoving`	Boolean	Indicates whether the camera is moving. Optional, default `false`.
`zoomMag`	Number	Zoom magnification. `1.0` means zoomed out. Optional.

jsonframe objects parameters

Parameter	Type	Description
`id`	Integer	ID of the object. Use this ID to start manual tracking.
`x`	Number	X coordinate of top left corner of the object.
`y`	Number	Y coordinate of top left corner of the object.
`width`	Number	Width of the object.
`height`	Number	Height of the object.

jsonframe zones parameters

Parameter	Type	Description
`profileId`	Integer	ID of the zone or profile.
`zoneType`	Integer	Type of the zone. The frontend uses this value only. Optional.
`enabled`	Boolean	Indicates whether the zone (profile) is enabled.
`polygon`	Array	A list of [x,y] coordinates.

Here's an example:

<MESSAGE >
<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.

{
    "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.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]
        }
    ],
    "trackerEnabled": true,
    "trackedId": 11215,
    "isMoving": true,
    "zoomMag": 2.234
}

Parameter	Type	Description
`objects`	Array	A list of moving objects visible on screen.
`id`	Integer	The object ID that will be used when starting manual tracking.
`x`	Double	The X coordinate of the top left corner of the object.
`y`	Double	The Y coordinate of the top left corner of the object.
`width`	Double	The object width.
`height`	Double	The object height.
`zones`	Array	A list of zones visible on screen.
`profileId`	Integer	The zone ID.
`zoneType`	Integer	The zone type.
`polygon`	Array	A list of [x,y] coordinates. Represents the corner of the profile/zone.

Tracker tracking event

The Autotracker app sends this Boolean event when the autotracking state changes. It indicates whether the autotracker is tracking.

{
    "name": "tnsaxis:CameraApplicationPlatform/tnsaxis:PtzAutotracking/tnsaxis:AutotrackingState",
    "niceName": "PtzAutotracking/PTZ Autotracking: Is tracking",
    "tags": {
        "isApplicationData": false,
        "isDeprecated": false
    },
    "availability": "Since AT 2.0"
}

Name	Type	isStateFul	Tags
`stateInfo`	int (0/1)	True	`{onvif-data}=Yes`, `{onvif-source}=No`
`channel`	int (1..1)	True	`{onvif-data}=No`, `{onvif-source}=Yes`
`triggerZoneId`	int (1..99)	True	`{onvif-data}=No`, `{onvif-source}=Yes`

For stateInfo: 0 means not tracking, 1 means tracking.

<MESSAGE > < Property >
<MESSAGE > Global Declaration Id: 631
<MESSAGE > Local Declaration Id: 217
<MESSAGE > Producer Id: 60
<MESSAGE > Timestamp: 1646907652.971824
<MESSAGE > [tnsaxis:topic0 = 'CameraApplicationPlatform']
<MESSAGE > [tnsaxis:topic1 = 'PtzAutotracking']
<MESSAGE > [tnsaxis:topic2 (PTZ Autotracking: Is tracking) = 'AutotrackingState' (PTZ Autotracking: Is tracking)]
<MESSAGE > [stateInfo = '1'] {onvif-data} {property-state}
<MESSAGE > [channel = '1'] {onvif-source}
<MESSAGE > [triggerZoneId = '3'] {onvif-source}

Triggers enabled event

The Autotracker app sends this Boolean event when the automatic trigger state changes. It indicates whether automatic triggers are active.

{
    "name": "tnsaxis:CameraApplicationPlatform/tnsaxis:PtzAutotracking/tnsaxis:AutoTriggers",
    "niceName": "PtzAutotracking/PTZ Autotracking: Autotracking triggers enabled",
    "tags": {
        "isApplicationData": false,
        "isDeprecated": false
    },
    "availability": "Since AT 2.2"
}

Name	Nice name	Type	isStateFul	Tags
`autoTriggersEnabled`		int (0/1)	True	`{onvif-data}=Yes`, `{onvif-source}=No`

<MESSAGE > < Property >
<MESSAGE > Global Declaration Id: 632
<MESSAGE > Local Declaration Id: 218
<MESSAGE > Producer Id: 60
<MESSAGE > Timestamp: 1646912108.470167
<MESSAGE > [tnsaxis:topic0 = 'CameraApplicationPlatform']
<MESSAGE > [tnsaxis:topic1 = 'PtzAutotracking']
<MESSAGE > [tnsaxis:topic2 (PTZ Autotracking: Autotracking triggers enabled) = 'AutoTriggers' (PTZ Autotracking: Autotracking triggers enabled)]
<MESSAGE > [autoTriggersEnabled = '0'] {onvif-data} {property-state}

Profile updated event

The Autotracker app sends this Boolean event when profile settings change. The profile number is included in the event name to make each profile event unique. The app sends the event each time the value changes.

{
    "name": "tnsaxis:CameraApplicationPlatform/tnsaxis:PtzAutotracking/tnsaxis:ProfileUpdated_xx",
    "niceName": "PtzAutotracking/PTZ Autotracking: Profile \"Profile 1\" updated",
    "tags": {
        "isApplicationData": false,
        "isDeprecated": false
    },
    "availability": "Since AT 2.2"
}

Name	Nice name	Type	isStateFul	Tags
`enabled`	Profile enabled	int (0/1)	True	`{onvif-data}=Yes`, `{onvif-source}=No`
`name`		string	False	`{onvif-data}=No`, `{onvif-source}=No`
`profileId`		int (0..99)	True	`{onvif-data}=No`, `{onvif-source}=No`
`channel`		int (1..1)	True	`{onvif-data}=No`, `{onvif-source}=No`

<MESSAGE > < Property >
<MESSAGE > Global Declaration Id: 634
<MESSAGE > Local Declaration Id: 220
<MESSAGE > Producer Id: 60
<MESSAGE > Timestamp: 1646912559.355492
<MESSAGE > [tnsaxis:topic0 = 'CameraApplicationPlatform']
<MESSAGE > [tnsaxis:topic1 = 'PtzAutotracking']
<MESSAGE > [tnsaxis:topic2 (PTZ Autotracking: Profile "Profile 1" updated) = 'ProfileUpdated_1' (PTZ Autotracking: Profile "Profile 1" updated)]
<MESSAGE > [enabled (Profile enabled) = '0'] {onvif-data} {property-state}
<MESSAGE > [name = 'Profile 1']
<MESSAGE > [profileId = '3']
<MESSAGE > [channel = '1']

Profile movement event

The Autotracker app sends this Boolean event when there is movement in a profile's trigger zone. The app sends the event when the value changes, but at most once every few seconds to avoid spamming. The profile number is included in the event name to make each profile event unique.

{
    "name": "tnsaxis:CameraApplicationPlatform/tnsaxis:PtzAutotracking/tnsaxis:ProfileMovement_xx",
    "niceName": "PtzAutotracking/PTZ Autotracking: Movement in profile \"Profile 1\"",
    "tags": {
        "isApplicationData": false,
        "isDeprecated": false
    },
    "availability": "Since AT 2.2"
}

Name	Nice name	Type	isStateFul	Tags
`movement`	Profile movement	int (0/1)	True	`{onvif-data}=Yes`, `{onvif-source}=No`
`name`		string	False	`{onvif-data}=No`, `{onvif-source}=No`

<MESSAGE > < Property >
<MESSAGE > Global Declaration Id: 635
<MESSAGE > Local Declaration Id: 221
<MESSAGE > Producer Id: 60
<MESSAGE > Timestamp: 1646912100.26449
<MESSAGE > [tnsaxis:topic0 = 'CameraApplicationPlatform']
<MESSAGE > [tnsaxis:topic1 = 'PtzAutotracking']
<MESSAGE > [tnsaxis:topic2 (PTZ Autotracking: Movement in profile "Profile 1") = 'ProfileMovement_1' (PTZ Autotracking: Movement in profile "Profile 1")]
<MESSAGE > [movement (Profile movement) = '0'] {onvif-data} {property-state}
<MESSAGE > [name = 'Profile 1']

Set automatic triggers event

Send this Boolean event to the Autotracker app to enable or disable automatic triggers.

{
    "name": "tnsaxis:CameraApplicationPlatform/tnsaxis:PtzAutotracking/tnsaxis:SetAutoTriggers",
    "tags": {
        "isApplicationData": false,
        "isDeprecated": false
    },
    "availability": "Since AT 2.2"
}

Name	Nice name	Type	isStateFul	Tags
`setEnabled`		int (0/1)	False	`{onvif-data}=No`, `{onvif-source}=No`

<MESSAGE > < Internal >
<MESSAGE > Global Declaration Id: 656
<MESSAGE > Local Declaration Id: 1
<MESSAGE > Producer Id: 680
<MESSAGE > Timestamp: 1646912908.717422
<MESSAGE > [tnsaxis:topic0 = 'CameraApplicationPlatform']
<MESSAGE > [tnsaxis:topic1 = 'PtzAutotracking']
<MESSAGE > [tnsaxis:topic2 = 'SetAutoTriggers']
<MESSAGE > [setEnabled = '1']

Set profile enabled event

Send this Boolean event to the Autotracker app to enable or disable a profile.

{
    "name": "tnsaxis:CameraApplicationPlatform/tnsaxis:PtzAutotracking/tnsaxis:SetProfile",
    "tags": {
        "isApplicationData": false,
        "isDeprecated": false
    },
    "availability": "Since AT 2.2"
}

Name	Nice name	Type	isStateFul	Tags
`profileId`		int (0..99)	False	`{onvif-data}=No`, `{onvif-source}=No`
`setEnabled`		int (0/1)	False	`{onvif-data}=No`, `{onvif-source}=No`

<MESSAGE > < Internal >
<MESSAGE > Global Declaration Id: 661
<MESSAGE > Local Declaration Id: 2
<MESSAGE > Producer Id: 697
<MESSAGE > Timestamp: 1646921730.312721
<MESSAGE > [tnsaxis:topic0 = 'CameraApplicationPlatform']
<MESSAGE > [tnsaxis:topic1 = 'PtzAutotracking']
<MESSAGE > [tnsaxis:topic2 = 'SetProfile']
<MESSAGE > [profileId = '1']
<MESSAGE > [setEnabled = '0']

Set temporary zone event

Send this event to the Autotracker app to create a temporary trigger zone on the current video screen view. Use this when an external trigger indicates there may be an object to track in the camera's current view. The only supported zone type is fullscreen.

{
    "name": "tnsaxis:CameraApplicationPlatform/tnsaxis:PtzAutotracking/tnsaxis:SetTemporaryZone",
    "tags": {
        "isApplicationData": false,
        "isDeprecated": false
    },
    "availability": "Since AT 2.2"
}

Name	Nice name	Type	isStateFul	Tags
`zoneType`		string ('fullscreen')	False	`{onvif-data}=No`, `{onvif-source}=No`
`timeout`		int (3..120)	False	`{onvif-data}=No`, `{onvif-source}=No`

Parameter	Type	Description
`timeout`	Integer	Time in seconds that the zone will be active.
`zoneType`	String	Zone type. Currently only supports `"fullscreen"`.

<MESSAGE > < Internal >
<MESSAGE > Global Declaration Id: 657
<MESSAGE > Local Declaration Id: 3
<MESSAGE > Producer Id: 682
<MESSAGE > Timestamp: 1646913333.250988
<MESSAGE > [tnsaxis:topic0 = 'CameraApplicationPlatform']
<MESSAGE > [tnsaxis:topic1 = 'PtzAutotracking']
<MESSAGE > [tnsaxis:topic2 = 'SetTemporaryZone']
<MESSAGE > [timeout = '15']
<MESSAGE > [zoneType = 'fullscreen']

Actions

Enable or disable automatic tracking

This action requests the Autotracker to change the setting for automatic tracking. When disabled, all profiles are disabled, but you can still start tracking by clicking on an object. When enabled, profiles send detection events and automatic tracking starts on enabled profiles.

If preset_name is not empty, the camera moves to the named preset before informing the Autotracker.

Available in fixed and continuous format:

com.axis.action.fixed.ptz-autotracking.autotriggers
com.axis.action.unlimited.ptz-autotracking.autotriggers

Parameter	Type	Description
`state`	Integer	`0`: Disabled, `1`: Enabled
`preset_name`	String	Empty string: don't move to preset.

Enable or disable automatic tracking for a profile

This action requests the Autotracker to change the enabled setting for a profile. When disabled, profiles inside the field of view still send detection events, but tracking does not start. When enabled, profiles send detection events and automatic tracking starts.

If preset_name is not empty, the camera moves to the named preset before informing the Autotracker.

Available in fixed and continuous format:

com.axis.action.fixed.ptz-autotracking.profile
com.axis.action.unlimited.ptz-autotracking.profile

Parameter	Type	Description
`profile_id`	Integer	0 or above
`state`	Integer	`0`: Disabled, `1`: Enabled
`preset_name`	String	Empty string: don't move to preset.

Create a temporary zone

This action requests the Autotracker to create a temporary zone to start tracking when an object has been detected by another application or sensor.

If preset_name is not empty, the camera moves to the named preset before informing the Autotracker.

Available in fixed format:

com.axis.action.fixed.ptz-autotracking.temp-zone

Parameter	Type	Description
`timeout`	Integer	Time in seconds. Range: 5 to 120.
`preset_name`	String	Empty string: don't move to preset.

Description​

Model​

Identification​

Version history​

Version 1.0​

Authentication​

Use cases​

Get supported versions​

Get settings​

Update current settings​

Set current viewport​

Get radar autotracking settings​

Get radar autotracking capabilities​

Update current radar settings​

API specifications​

getSupportedVersions​

getApplicationSettings​

setApplicationSettings​

getAutotrackingSettings​

setAutotrackingSettings​

Get and set viewport configuration (rotation)​

getViewportConfig​

setViewportConfig​

getAutotrackingTarget​

setAutotrackingTarget​

getAutotrackingState​

setAutotrackingState​

addProfile​

getProfile​

updateProfile​

deleteProfile​

setTempZone​

getRadarAutotrackingSettings​

setRadarAutotrackingSettings​

getRadarAutotrackingCapabilities​

addRadarProfile​

getRadarProfile​

updateRadarProfile​

deleteRadarProfile​

sendTestAutotrackingEvent​

General error codes​

Events​

Object stream description​

objectStream event​

Tracker tracking event​

Triggers enabled event​

Profile updated event​

Profile movement event​

Set automatic triggers event​

Set profile enabled event​

Set temporary zone event​

Actions​

Enable or disable automatic tracking​

Enable or disable automatic tracking for a profile​

Create a temporary zone​

Description

Model

Identification

Version history

Version 1.0

Authentication

Use cases

Get supported versions

Get settings

Update current settings

Set current viewport

Get radar autotracking settings

Get radar autotracking capabilities

Update current radar settings

API specifications

getSupportedVersions

getApplicationSettings

setApplicationSettings

getAutotrackingSettings

setAutotrackingSettings

Get and set viewport configuration (rotation)

getViewportConfig

setViewportConfig

getAutotrackingTarget

setAutotrackingTarget

getAutotrackingState

setAutotrackingState

addProfile

getProfile

updateProfile

deleteProfile

setTempZone

getRadarAutotrackingSettings

setRadarAutotrackingSettings

getRadarAutotrackingCapabilities

addRadarProfile

getRadarProfile

updateRadarProfile

deleteRadarProfile

sendTestAutotrackingEvent

General error codes

Events

Object stream description

objectStream event

Tracker tracking event

Triggers enabled event

Profile updated event

Profile movement event

Set automatic triggers event

Set profile enabled event

Set temporary zone event

Actions

Enable or disable automatic tracking

Enable or disable automatic tracking for a profile

Create a temporary zone