Eagle Eye API Polling

One of our most common requests is, “How do I put my camera on my website?”. It has always been possible, but the aim of this blog post is to make it more accessible for everyone. Let’s start with how our API is architected. There are two main concepts to know when working with our API. First is our real-time event stream (referred to as our poll stream). The second is how we manage video.

Eagle Eye provides two video streams for each camera. The first is the full resolution, unmodified stream from the camera. The other is what we call the preview stream. It is a lower resolution version of the full video stream. We provide the preview stream as a series of JPEG images.

Working with straight video is hard. We make it easier by providing a low-resolution JPEG image stream from each camera. If you replace this image every second, you can make a very basic “video.” The poll stream notifies you whenever a new image is available for you to replace the old one with.

Step 1: Login

The first step in working with our API is to login with your username, password and API key. All requests to our API should include the API key that you created. After the Authentication step, you will get a token which you will then need to pass into the Authorization step. We automatically return you the user information for the user who just logged-in.

After successfully completing the login process you will get a session cookie to use on all calls during the remainder of your session. Note: you can change the cookie expiration length as a user account setting.

Step 2: Get available devices

The currently logged-in user is able to get information about what devices they have been given access to. The process for listening to bridge and cameras events is the same. With the obvious difference that cameras provide video streams.

Step 3: Subscribe to the poll stream

You subscribe to the poll stream by passing the devices and the resources that you are interested in receiving. In this case, we just need to know when there is a new preview image available. You can subscribe to more. It is the same concept to monitor everything about each device. This works for status, motion events, recording events, analytics, setting changes, etc.

After you subscribe to the poll stream you will get back the latest state for the resources that have been requested. You can use this as a starting point to display this information. For all subsequent requests, you will be notified of all changes going forward. Subscribing returns another cookie. This cookie is used to remember when you were last updated. You will need to pass this in addition to the authorization cookie.

If your needs change, the connection is interrupted, or your polling session cookie expires you can always re-subscribe to get the latest values and be back in sync.

Step 4: Check for events

You should continue to check the poll stream for new events. The poll stream will return the latest values each time you check. Depending on your application, you can check the poll stream immediately after getting a response. The response is based on the poll session cookie and the recommended pattern is to immediately open a new connection each time you get a response.

This also allows your interface to adapt to changing bandwidth conditions. If the network connection slows down and you can not get a preview image every second, you can still listen to the poll stream every second and only update the preview image after the previous has loaded. This means you interface will gracefully degrade to handle bandwidth and latency changes.

Step 5: Process events

As events come in on the poll stream you can decide what to do with them. For example, we track which cameras on the screen and don’t process those events to update the preview stream until those cameras are back in view. For things like status or analytic events, you may want to continue processing that data on every update to keep your data in sync.

Some events will last longer than a single iteration through this loop. We refer to these as span events, and at the end of a span event, we provide the start and end times together so that you have the canonical timestamps for the event.

What else can we do with this?

Inside the last step is usually where our Technology Partners work their unique brands of magic. Some customers will use facial recognition to aid access control systems or assist retail loss prevention teams. Others will use the analytics events to adjust the predicted staffing needs in the future. Please feel free to reach out to us directly at [email protected].

Learn About our Developer Program