Ivideon Open API: First Steps

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

If you don’t know who we are, we’ll explain in four words: a video surveillance service via the Internet. For the rest of the details, we refer to the very first article .

So Ivideon was engaged in a worthwhile project - the Open API. Yes, this is an open API that allows our customers and partners to simplify and automate interactions with our service. And even create new products!

The project is still in beta testing, but you can try the API if you wish. We will tell you more about this at the end of the article.



How we came to the Open API

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

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

Structure

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

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

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

Features

Using the Open API, you can create your own alternative to your Ivideon account. You can export the video on demand, set up a regular event that will request the video once a day for a certain period of time, 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 their needs. This applies to colors, pictures, buttons, appearance, style, and so on, so that everything visually fits into any client system.

A separate branch of functions is associated with events. The essence is this: in a third-party system, the user can create events, publish it in our API, and the camera will record a video clip for this event. 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 that are not directly related to the cameras - for example, a door opened, a motion sensor worked, and so on. We are also working on a function that will either replace these clips, or will complement them - this is a record from beginning to end.

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 features for themselves. Since our cameras have a motion detector 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 looking for a way to simplify the transfer of access rights to cameras. By default, Ivideon through the web interface allows you to transfer rights to view online, transfer rights to view the archive and transfer rights to control cameras (move cameras, turn on and off). However, all these rights had to be transferred manually: select the camera, select the user's e-mail, indicate which rights to transfer to him. When you have 10 cameras, one person can handle it. When you have hundreds of cameras scattered all over Russia and dozens of users, a severe pain begins.

As you understand, it is very inconvenient to consider all transfers of rights. Using technology called Camera Grouping, it will be possible to specify a hierarchy: for example, a large region, a city in a region, individual areas in a city, and so on. Cameras can be distributed throughout the tree, and give a person access (or withdraw access) immediately to a specific group of cameras.



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

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

This system lacked the most important thing - video surveillance. But what if the courier steals a bicycle from the garage? Ideally, it was necessary to see that the courier came, brought the package and left, taking nothing with him. To do this, you can publish the event in the application directly at the right time, and at the same time record a clip. You can also conduct live streaming directly to the mobile application. Such a system is easy to implement using a suitable microcontroller and any camera with Ivideon on board.

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



Suppose you receive education remotely, and process all the lectures at home, but you still have to come to exams. At the same time, you can take exams with the help of a video surveillance system. In the presence of the proctor, computer testing of the student’s knowledge takes place. First, identification occurs, for example, a demonstration of a passport. Then there is the issuance of tasks, interviewing with a specific person. In the process, the teacher broadcasts video from the webcam and from the screen. The record is stored for some time in the cloud and in case of contentious 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 you to add video analytics to video surveillance - the scope for introducing new features is huge. It is difficult to imagine now whether you can search for Pokemon using CCTV cameras, but you will definitely find out about a potentially dangerous event registered by the camera.

For small and medium-sized businesses, one of the most vulnerable places (financially) is located immediately at the checkout. Identification of template algorithms for the cashier’s actions helps to identify theft or misconduct (when the cashier does not serve customers, but is busy with his affairs). The video surveillance system monitors cash events in parallel with the video recording recorded by the camera, allowing you to visually determine the fact of fraud. The simplest example: if the buyer has not taken the check, then it does not have to be “closed” or fiscalized - the cashier cancels the check and takes the money for himself.

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

DIY example of using the Open API

One of the interesting examples of using the Open API is in the field of home automation. For example, someone rings your doorbell, the camera responds and records, and then sends you an event notification.

The Ivideon API uses OAuth 2.0 for authorization, requests are sent to the openapi-alpha.ivideon.com server . To use the Oauth 2.0 protocol, we need 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": "archive attachment_tokens cameras_list cloud_recording get_events live manage_events manage_groups mute_camera_alerts servers_management shared_archive shared_live subscribe_events turn_off_camera user_info users_management voice-messaging",
    "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 pass access_token and camera ID to it. The player will receive a video from Ivideon Cloud. After gaining access, you can configure all the SDK components: color, text, language, and much more.



Event Creation: Record a video and send a 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 are using events, you need to re-request the status of the event.

{
    "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/H1xyCDXSsRl4TqBkWQUfHDTHIQlfDMS1.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 pick it up.

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

How to contact and gain access

So far we have only a few test projects, i.e. we accept applications on an individual basis and with each personally find ways to interact. While we are in beta testing, you will need to write to us and we will send you an integration kit: SDK, login / password for the API, 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 work are present there. You can apply ( integration_support@ivideon.com) and test the work on the example of your smart home, startup or business.