Using the VMS PTZ API

What is the Nx Witness API request to perform PTZ commands?

/api/ptz can be used to perform a PTZ read or write operation with 2 required parameters: camera ID and PTZ command.

Read the Camera Identifiers support article to see how you can obtain a camera ID. View the chart below to see a list of supported PTZ commands and their parameters.

How to perform a PTZ command via Nx Witness API?

1. [Optional] Check if the camera supports PTZ functionality.
2. Initiate the API request with Nx Witness Server. Parameters should be passed as a JSON object in the POST message body with content type "application/json".
3. Enter your credentials to verify the API request and perform the PTZ command.

import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth
import time
import urllib3

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

USERNAME = 'local account username'
PASSWORD = 'local account password'
SERVER_URL = 'server ip and port'  # https://<server_ip>:<sever_port>
CAMERA_ID = '7f430fb3-b3f7-362b-7de5-4de46386c343'

ptz_dict = {'NoPtzCapabilities': 0, 'ContinuousPanCapability': 1, 'ContinuousTiltCapability': 2,
            'ContinuousZoomCapability': 4,
            'ContinuousFocusCapability': 8, 'ContinuousRotationCapability': 536870912, 'AbsolutePanCapability': 16,
            'AbsoluteTiltCapability': 32, 'AbsoluteZoomCapability': 64, 'AbsoluteRotationCapability': 1073741824,
            'RelativePanCapability': 1024, 'RelativeTiltCapability': 2048, 'RelativeZoomCapability': 16384,
            'RelativeRotationCapability': 32768, 'RelativeFocusCapability': 8388608, 'ViewportPtzCapability': 128,
            'FlipPtzCapability': 256, 'LimitsPtzCapability': 512, 'DevicePositioningPtzCapability': 4096,
            'LogicalPositioningPtzCapability': 8192, 'PresetsPtzCapability': 65536, 'ToursPtzCapability': 131072,
            'ActivityPtzCapability': 262144, 'HomePtzCapability': 524288, 'AsynchronousPtzCapability': 1048576,
            'SynchronizedPtzCapability': 2097152, 'VirtualPtzCapability': 4194304, 'AuxiliaryPtzCapability': 16777216,
            'NativePresetsPtzCapability': 134217728}


def check_status(response, verbose):
    if response.status_code == requests.codes.ok:
        if verbose:
            print("Request successful\n{0}".format(response.text))
        return True
    print(response.url + " Request error {0}\n{1}".format(response.status_code, response.text))
    return False


def request_api(url, uri, method, **kwargs):
    server_url = f'{url}{uri}'
    response = requests.request(
        method,
        server_url,
        **kwargs
    )
    if not check_status(response, False):
        exit(1)
    if response.headers.get('Content-Type') == 'application/json':
        return response.json()
    else:
        return response.content


def check_ptz_capability(ptz_value, ptz_capability):
    return int(ptz_value) & ptz_dict[ptz_capability]


def main():
    #STEP 1
    camera_info = request_api(SERVER_URL, f'/ec2/getCamerasEx?id={CAMERA_ID}', 'GET',
                              auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)
    camera_info = camera_info[0]['addParams']
    for item in camera_info:
        if item['name'] == 'ptzCapabilities':
            ptz_value = item['value']
            break
    else:
        print("Cannot find information about camera's PTZ capabilities")
        exit()

    if check_ptz_capability(ptz_value, 'NoPtzCapabilities'):
        print('Does not support PTZ')
        exit()

    #STEP 2-3
    request_api(SERVER_URL, f'/api/ptz?cameraId={CAMERA_ID}&command=GetDevicePositionPtzCommand', 'GET',
                auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)

    if check_ptz_capability(ptz_value, 'ContinuousPanCapability'):
        request_api(SERVER_URL, f'/api/ptz?cameraId={CAMERA_ID}&command=ContinuousMovePtzCommand&xSpeed=1&ySpeed=0&zSpeed=0',
                    'GET', auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)
        time.sleep(1)

        request_api(SERVER_URL, f'/api/ptz?cameraId={CAMERA_ID}&command=ContinuousMovePtzCommand&xSpeed=0&ySpeed=0&zSpeed=0',
                    'GET', auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)

    if check_ptz_capability(ptz_value, 'PresetsPtzCapability'):
        request_api(SERVER_URL, f'/api/ptz?cameraId={CAMERA_ID}&command=ActivatePresetPtzCommand&presetId=1&speed=1.0',
                    'GET', auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)


if __name__ == '__main__':
    main()