Overview
3VR Appliances and Enterprise Appliances support several APIs which can be accessed using web services. This has two key advantages for those writing client applications:
These APIs can be used by client applications remotely across a network.
Client applications can be written in almost any programming language.
3VR's Web Services APIs are based on standard protocols and formats such as HTTP, XML, REST, and SOAP which are supported in all major programming environments. In addition, the 3VR Web Services SDK contains sample code and support libraries for several popular programming languages.
In total, the 3VR Web Services API is comprised of 4 APIs:
The 3VR REST API gives client programs access to camera information, system settings, health monitoring data, video, images, and more with RESTful HTTP requests
The 3VR External System Activity API (SOAP) is used by client programs to add events to the 3VR system's database. These include bridges to Point of Sale (POS) systems, access control systems and transaction recording systems. The External System Activity API uses a Simple Object Access Protocol (SOAP) binding that lets client applications define event types and metadata types and inject individual events.
The 3VR External Query API lets client programs query for specific events in the set of events recorded by the 3VR system. 3VR provides RESTful access to some of the most common queries, but client programs can also send custom XML-based queries to return only events of interest. Regardless of which method is chosen, events are returned in XML format and use URLs to reference associated images and videos.
The 3VR Live Query API allows client programs to receive a continuous stream of new events matching an XML query. Clients can choose feeds based on the type of event or whether the event has a particular alert associated with it. The Live Query API uses the same XML predicate request as the External Query API, except the appliance will returns a continuous stream of events instead of a fixed set.
Application developers may use one API or a combination of APIs depending on their needs.
What does an Event mean?
3VR's "Searchable Surveillance" model is built around the creation of events. An event represents an action detected by the 3VR system, such as motion observed by a camera or the detection of a specific face. An event consists of two main components:
Event data: pieces of information such as the date, camera number, transaction ID, etc.
Event video: a video clip from the time when the event occurred.
Each event captured by the 3VR system is represented in OpCenter by an event card. Event cards are labeled with the type of event, the date and time the event card was created, and other information about the event.
The simplest event type is a Motion event. Motion events are created when the system detects movement in a camera's field of view. All motion event cards contain the following elements in storyboard view:
Images: each motion event card displays up to three still frames from the event:
Camera number and name: the number and name of the camera that captured the motion event.
Event start time: the time that motion was first detected by the camera.
Event duration: the length of time continuous motion was detected.
In addition to basic video recording, events can be generated by integration with external systems (e.g. transaction, access control, POS, etc.) and analytics plug-ins.
Choosing the Right API
Before embarking on a project using a 3VR API, application developers should carefully review each API's description and sample code to ensure they have selected the correct API(s) for their purposes. The following guidelines apply:
To create events on the 3VR appliance, use the 3VR External System Activity API
To request and obtain events from the 3VR Appliance that match certain criteria (date, camera, event type, etc.) use the 3VR External Query API.
To request and obtain a continuous stream of events matching a query, use the 3VR Live Query API.
To request information about a 3VR Enterprise Appliance, a single appliance, a camera, or to obtain video or images from a particular camera, use the 3VR REST API.
There are two approaches to developing with the 3VR API: you can either work with the API directly using libraries provided in your programming language of choice, or use 3VR's helper code provided for the language in which you are programming. Both approaches are supported, and the approach you choose will depend on your particular circumstances.
Even if you are writing directly to your language's interfaces, you may find it useful to review the helper code. The source code to the helper code is included in the SDK.
What’s in the SDK?
This manual is associated with a Software Development Kit that has useful tools for programming with 3VR Web services. These include specification files, such as XML schemas, WSDL files, library bindings, source code, and samples of real applications built using these APIs. Also included is a copy of the API documentation in PDF form.
Structure of the API Documentation
3VR's API documentation contains sections for each of the individual APIs. All users should read this overview and the "Getting Started" section, and then proceed to the documentation for their API of choice.
All of the API-specific sections contain information on the format of the request to the appliance and what to expect in return.
The 3VR External System Activity API and the 3VR External Query API also include sample code to demonstrate the format of the
XML request predicate. The 3VR External System Activity API currently includes examples in C# and Java. The 3VR External Query API
has examples in Java and Python. Contact your 3VR representative if you are interested in writing client code in other languages.
The final section contains reference material on the structure of XML-formatting for use in specifying queries and processing the
events returned from queries.