Open Ivideon API: First Steps

How quickly time flew by: our previous post came out on Habré 2 years ago. When you are silent for so long, you are either dead, or you work hard to at one moment explode with news and tell something worthwhile.

If you do not know who we are, then we will explain in four words: video surveillance service via the Internet. For the rest of the details refer to the very first article .

So in Ivideon we were engaged in a worthwhile project - Open API. Yes, it is an open API that allows our customers and partners to simplify and automate the interaction with our service. And even create new products!
')
The project is still in beta testing, but you can try the API if you wish. More details about this at the end of the article.



How we came to the Open API

We came to the idea of ​​starting the development in the easiest way - customers asked for the ability to manage Ivideon as a service: independently connect and disconnect video surveillance cameras, change tariff plans, manage camera settings, change the recording quality and schedule, increase or decrease the volume, play the recording client application or website.

Once there is a demand, it means that we had to provide a proposal: to provide our interface to other companies and users, having well structured it and having written intelligible documentation.

Structure

In parallel with the API, the development of our integration components of the SDK, which are responsible for reproduction, was going on: this is the Web SDK written in Javascript and the Mobile SDK. Both SDKs are based on a modified video player from the VLC project that is used to play live video and archived video on a web page or in a mobile application. That is, this fork directly VLC library with a fairly large number of additions, and optimizations, which we did ourselves.

The algorithm of actions of our system implies the appearance of some delays, but we have implemented a pre-buffer on cameras, recording video several seconds before the event occurred. The pre-buffer allows you to compensate for any network delays.

The pre-buffer stores the last 5 seconds (approximately) of a live video, but the camera does not send it anywhere. If a request comes in, the camera starts recording, takes the last 5 seconds and also sends them. Therefore, in any request, we include a slightly earlier video than noted by the request itself.

Opportunities

Using the Open API, you can create your own alternative to your Ivideon account. You can export video on demand, set up a regular event that will request video for a certain period of time once a day, receive a link to the video and download it to yourself. We strive to ensure that all available components can be customized by the client to fit their needs. This applies to colors, pictures, buttons, appearance, style, and so on, so that everything visually fits into any client system.

A separate function branch is associated with events. The point is this: in a third-party system, a user can create events, publish it in our API, and the camera for this event will record a video clip. Now she is recording an exceptionally short clip, in the region of 10-30 seconds. The development of this function makes it possible to record clips for some external events not directly related to the cameras - for example, the door opened, the motion sensor triggered, and so on. We are also working on a function that will either replace these clips, or become an addition to them - this is a record from start to finish.

Types of use



There are two schemes for how everything works: for personal use and when the client acts as a reseller.

The first scheme is suitable for ordinary users who just want to automate something, as well as for large companies that use the Open API capabilities for themselves. Since our cameras have motion detection and a sound detector, using the API you can integrate the system into your smart home: receive SMS at some event, request live video, etc.

According to the second scheme, a business partner that is integrated with us can create other users, that is, resell services to its customers.

Examples of using



One of our major partners installed hundreds of cameras and began to look for a way to simplify the transfer of access rights to cameras. By default, Ivideon via the web interface allows you to transfer viewing rights online, transfer viewing rights to the archive and transfer rights to control cameras (move cameras, turn on and off). However, all these rights had to be transferred manually: select a camera, select the user's e-mail, specify which rights to transfer to him. When you have 10 cameras, one person can handle it. When you have hundreds of cameras scattered throughout Russia, and dozens of users, severe pain begins.

As you understand, it is very inconvenient to take into account all transfer of rights. With the help of technology, which was called “Camera grouping”, it will be possible to indicate a hierarchy: for example, a large region, a city in a region, particular areas in a city, and so on. Cameras can be distributed throughout the tree, and you can give a person access (or pick up access) immediately to a certain group of cameras.



The following example of using the Open API will be of interest to ordinary users as well, since it affects the functionality of the smart home. Among our customers there are several companies involved in smart home technology. For example, in the USA there is a team that develops a system that allows you to open a garage or a separate room, passing one-time generated code access to third parties.

Your home itself will take the parcel for you while you are away. The courier arrives with the cargo, receives a one-time code that opens the garage, puts the package there, after which the door closes and is locked.

This system lacked the most important thing - video surveillance. What if the courier steals a bike from the garage? Ideally, it was necessary to see that the courier came, took the package and left, without taking anything with him. To do this, you can publish the event in the application directly at the right time, and at the same time record the clip. You can also keep a live broadcast all the time right in the mobile application. Such a system is easy to implement with the help of a suitable microcontroller and any camera with Ivideon on board.

When an event occurs that should be followed by video recording, an event identification must be set on the central controller of the smart home - it will be sent to us, after which our cloud will send a “write” command to the camera. Then you send us a request and get a link where you can download a video clip, send it somewhere or embed it.



Suppose you get an education remotely, and you process all the lectures at home, but you still have to take exams. At the same time, exams can be taken with the help of video surveillance systems. In the presence of a proctor, a computer test of the student’s knowledge takes place. First there is an identification, for example, a demonstration of a passport. Then there is the issuance of assignments, interviewing with a specific person. The teacher is in the process of broadcasting video from the webcam and from the screen. The record is stored for some time in the cloud and in case of any disputable issues is provided to the parties to the conflict.



We have previously integrated with corporate and business applications (ACS, OPS, cash registers), but the development of the API allows us to add video analytics to video surveillance - a huge amount of space for introducing new features. It is difficult to guess now if you can search for Pokemon with the help of video surveillance cameras, but you will definitely know about a potentially dangerous event registered by the camera.

For small and medium businesses, one of the most vulnerable places (in financial terms) is located right at the cash register. Identifying the template algorithms of actions of the cashier helps determine theft or misconduct (when the cashier does not serve customers, but is busy with his own affairs). The video surveillance system monitors cash events in parallel with the video captured by the camera, allowing you to visually determine the fact of fraud. The simplest example: if the buyer did not take the check, it does not have to be “closed” or fiscalized - the cashier cancels the check and takes the money for himself.

Monitoring events at point-of-sale terminals is just one of the possible options. If someone wants to put surveillance cameras on the beach in the future and find all people with a mole in the shape of a five-pointed star, Ivideon will connect to the solution. :-)

DIY example of using Open API

One of the interesting examples of using the Open API is in the area of ​​home automation. For example, someone calls you at the door, the camera responds and records, and then sends you an event notification.

Ivideon API uses OAuth 2.0 for authorization, requests are sent to the openapi-alpha.ivideon.com server. To work with Oauth 2.0, we need an access_token.

 POST / auth / oauth / token HTTP / 1.1
 Host: openapi-alpha.ivideon.com
 Content-Type: application / x-www-form-urlencoded
 Authorization: Basic S2V5cmRwbHk6YjhmQzRkYTMxZTQwZWZkMTkxZDAwMzETM2FkZDcwZGU =
 Cache-Control: no-cache
 
 grant_type = password & username = {user_name} & password = {user_password}


 {
     "api_host": "openapi-alpha-eu01.ivideon.com",
     "access_token": "100-U6c3d3e17-c845-4d13-bf57-6fd99ea7807a",
     "expires_in": 3600,
     "token_type": "Bearer",
     scope
     "owner_type": "user",
     "refresh_token": "e95bed0c5fb2413b8d6e55d8dcf16630",
     "owner_id": 100001043052
 }

To get token you need to specify the username (user_name in the example) and password (user_password in the example) and client_id and client_secret in the HTTP Basic Authorization header.

To use the SDK, you need to give it the access_token and camera ID. The player will receive a video from Ivideon Cloud. Once accessed, you can customize all the components of the SDK: color, text, language, and more.



Create an event: record video and send notification.

 POST / events? Op = CREATE & access_token = {access_token} HTTP / 1.1
 Host: openapi-alpha-eu01.ivideon.com
 Content-Type: application / json
 Cache-Control: no-cache

 {
     "type": "eventType",
     "time": 1464263172,
     "clip_settings": {
         "duration": 60
     },
     "notify": true
     "device_id": "100-6a18e46fc9ab4219261bee3bfb6cda35: 0",
     "device_type": "camera"
 }
 {
   "result": {
     "status": "new",
     "delivered": true
     "preview": null,
     "clip": null,
     "type": "eventType",
     "user": 100001043052,
     "device_type": "camera",
     "time": 1464263172,
     "clip_duration": null,
     "_id": "Xl3149lugdmF8sO4.1",
     "data": null,
     "id": "Xl3149lugdmF8sO4.1",
     "device_id": "100-6a18e46fc9ab4219261bee3bfb6cda35: 0"
   },
   "success": true
 }

If you use events, you need to re-request the status of the event again.

 {
     "result": {
         "status": "new",
         "delivered": true
         "preview": "https://msk88.ivideon.com/preview/motion/2016-07-21/gAS0dis1gsvLsf3REn0eTQWbRwkHAkN1.jpeg",
         "clip": "https://msk98.ivideon.com/events/clips/2016-07-21/H1xyCDXSsRl4TqBkWQUfHDTHIQlfMS1.mp4",
         "type": "motion / started",
         "user": "4005500726931",
         "device_type": "camera",
         "time": 1469096014,
         "clip_duration": 4,
         "data": null,
         "id": "8cgclg2IFQYo4hFv.21",
         "device_id": "100-b6251a97fa9d26c8952f786ecefa9551: 0"
     },
     "success": true
 }

In preview - photo, in clip - video. As soon as they appear there - you can take.

You can see other examples of queries in our integration guide when it is published.

How to contact and access

We still have only a few test projects, i.e. we accept applications individually and personally find ways to interact with each. While we are in beta testing, you will need to write to us and we will send you an integration kit: SDK, API login / password, documentation, etc. In the future, all this will be available out of the box.

Now the API is fully functional, that is, all the functions that are necessary for full-fledged work are present there. You can apply ( integration_support@ivideon.com ) and test the work on the example of your smart home, startup or ready business.