Getting started with the HTTP API

Camera Software Administration
, , , ,
1

Introduction

An application-programming interface (API) is a set of programming instructions and standards for accessing a software application or Web tool. An API is a software-to-software interface, not a user interface. With APIs, applications talk to each other without any user knowledge or intervention.

MOBOTIX HTTP API

The HTTP API (Application Programming Interface) is a software interface to the camera and allows to conveniently integrate the camera into a centralized management system. The interface consists of several CGI scripts that can be called with parameters and values using HTTP commands. By means of these scripts, you can modify the settings of the dialogs in Setup Menu and execute certain camera functions.

Most common uses

  • Modification of the configuration: recordings, events, actions, etc.
  • Modification of the image settings: exposure, image quality, image resolution, etc.
  • Status requests
  • Triggering of actions

API HTTP request description

A normal HTTP request from the browser looks like this:
http://<ip_address_for_the_camera>/control/control?list&section=recording

which can be split in the following:

  • protocol: http://
  • destination: <ip_address_for_the_camera>
  • cgi-call: /control/control
  • parameters: list&section=recording

so a well formed request is of the form:
protocol + destination + cgi-call + parameters

The previous request will deliver the following HTTP response:

imagen
imagen.png3358×1884 834 KB

where the current configuration options for recordings are visualized.

CGI Calls

/control/control

Using the HTTP command
http://<ip_address_for_the_camera>/control/control

you can modify the settings of the Setup menu. Type
http://<ip_address_for_the_camera>/control/control?list

to display the different sections available.

imagen
imagen.png1202×972 166 KB

/admin/control

Using the HTTP command
http://<ip_address_for_the_camera>/admin/control

you can modify the settings of the Admin menu. Type
http://<ip_address_for_the_camera>/admin/control?list
to display the different sections available.

imagen
imagen.png1154×538 105 KB

/control/rcontrol and /admin/rcontrol

Using the HTTP command
http://<ip_address_for_the_camera>/control/rcontrol?list

you can visualize specific actions which can be executed
http://<ip_address_for_the_camera>/control/rcontrol?action=sound&soundfile=Alarm

by calling this HTTP request the camera will play a sound file.

Some of these functions can only be called as an admin user

imagen
imagen.png1368×92 26.9 KB

in this case the HTTP Request would be:
http://<ip_address_for_the_camera>/admin/rcontrol?action=reboot

vPTZ Settings

As a consequence of integrating the Q camera models, the cameras offer vPTZ features (virtual Pan/Tilt/Zoom) also in the HTTP API. The corresponding features have been documented on specific help dialogs, which can be opened using the corresponding links:

click.cgi

This interface provides limited access to simple vPTZ features.
http://<ip_address_for_the_camera>/control/click.cgi?help

rotor.cgi

This interface provides full access to all vPTZ features.
http://<ip_address_for_the_camera>/control/rotorcgi?help

control?list&section=vptzcontrol

control also provides access to some vPTZ features, as outlined in the vptzcontrol section.
http://<ip_address_for_the_camera>/control/control?list&section=vptzcontrol

Image CGI-Calls

Additionally there is a set of CGI calls to retrieve live images, video streams and recordings of the camera directly from the integrated web server.

/record/current.jpg

http://<ip_address_for_the_camera>/record/current.jpg

  • Retrieves a camera image according to the current image settings
  • You cannot specify any additional parameters

/cgi-bin/image.jpg

http://<ip_address_for_the_camera>/cgi-bin/image.jpg

  • Retrieves a camera image using additional image parameters.
  • The saved configuration is not changed and does not affect the live image.

http://<ip_address_for_the_camera>/cgi-bin/image.jpg?camera=right&size=320x240&quality=60

  • camera=right is the right lens on dual cameras
  • size=320x240 is the resolution of the image
  • quality=60 is the quality percentage

Appending ?help to the end of the command will display the corresponding help page with all the options available:
http://<ip_address_for_the_camera>/cgi-bin/image.jpg?help

/cgi-bin/faststream.jpg or /control/faststream.jpg

Retrieves the live stream from the camera using additional image parameters.

  • /cgi-bin/faststream.jpg with guest access
  • /control/faststream.jpg with user access

/control/event.jpg

Provides access the camera’s events and allows adding additional parameters.
http://<ip_address_for_the_camera>/cgi-bin/event.jpg

The following request, for example, delivers the last event image of the camera:
http://<ip_address_for_the_camera>/control/event.jpg?sequence=head

Appending ?help to the end of the command will display the corresponding help page with al the options available:
http://<ip_address_for_the_camera>/control/event.jpg?help

Additional help

The help pages on the camera provide an overview of the API commands and addtional examples. The help pages can be accessed clicking on the ? icon on the top right corner of the camera web interface or via the url:

http://<ip_address_for_the_camera>/help/help

Down at the bottom of the MOBOTIX Online Help is the Remote-Controlling section

imagen
imagen.png816×202 36.7 KB

1 Like