Evercam.io API

Welcome to the Evercam V1 API documentation. Here you'll find all the API references and links to client libraries that you'll need to get

Base URI

https://api.evercam.io/v1

The evercam REST API supports multiple different authentication mechanisms to ensure that whatever environment you find yourself in, we’ve got you covered. This section of the documentation outlines the various methods available.

Basic

To make it as easy as possible for developers to quickly test and learn the various resource actions available we’ve enabled HTTP basic authentication using your username (or email) and password. The following cURL command illustrates this authentication method.

curl -X GET https://api.evercam.io/v1/... \
-u {username}

Session

As evercam utilises cookies to maintain a users session once they have been logged in, any ajax requests originating from the same user agent can be told to include the apprioriate credentials. This can be achieved in jQuery in the following way:

jQuery.ajax({
  url: 'https://api.evercam.io/v1/...',
  xhrFields: {
    withCredentials: true
  },
  statusCode: {
    200: {
      ...
    },
    ...
  },
  ...
});

OAuth 2.0

Implicit Grant

Our implementation supports the implicit grant type which can be used to obtain access tokens. It is optimised and secured for clients with a predetermined set of redirect uris. Typically this means a browser using javascript. It is a redirection-based flow which, when successfully authorized, results in the browser being directed back to the client application with an access token appended to the fragment portion of the redirect uri. The process starts with the client (you) redirecting the user (their browser) to our authorization endpoint with the following querystring parameters. Values surrounded with curly braces { } are required, those surrounded by square brackets [ ] are optional.

https://www.evercam.io/oauth2/authorize...

?response_type=token
&client_id={your evercam client id}
&scope={the access scopes you wish to use}
&redirect_uri=[one of your registered callback uris] // optional
&state=[a value you choose to help prevent CSRF] // optional

If the user has previously granted your application access to all the resources requested in the scope parameters, or if the user chooses to now authorize those scopes, evercam will generate a new access token and redirect the user back to the either the redirect_uri parameter you provided or to the default callback uri associated with your client account when you registered. The access token and its duration will be appended as part of the uri fragment as follows:

https://{redirect_uri}#access_token=410d79341e45c915&token_type=bearer&expires_in=3600

If the user declines your authorization request or if your request is malformed or invalid then the user will be redirected back to the {redirect_uri} (or default callback uri) with an error status and message as follows:

https://{redirect_uri}#error=access_denied&error_description=some+error+message&state={your state}

Should the client_id parameter be invalid or the redirect_uri parameter not match one of the values you have registered with your account then the user will be shown an error on the evercam site.

Evercam.js

Evercam.js allows you to easily access all evercam.io APIs and also works as jQuery plugin which can easily show image from any evercam-enabled camera on a website. jQuery is dependency and it has to be included before evercam.js.

Including Evercam.js

Edit your HTML page and put following two lines inside head tag

<script src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
<script src='http://cdn.evercam.io/js/v1/evercam.js'></script>
So it will look like this:
<!DOCTYPE html>
<html>
<head>
  <title></title>
  <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
  <script src='http://cdn.evercam.io/js/v1/evercam.js'></script>
</head>
<body>

</body>
</html>

Showing camera snapshots

Via attributes

Simplest way to show image from camera on your website is to just add img tag with evercam specific attributes. Evercam.js will automatically load camera image into img tag with ‘evercam’ attribute set to stream name and refresh it every X seconds times 1000 (set in ‘refresh’ attribute). Typical camera image resolution is 640x480 pixels but you can adjust it to your needs using width and height parameters. Following line of code will get new snapshot from camera every 5 seconds and display it as 320x240 pixels image:

<img evercam='dublin-rememberance-floor2' width="320" height="240" refresh='5000' />
Following html page will display camera image on full screen and update it every 2 seconds:
<!DOCTYPE html>
<html>
<head>
<title></title>
  <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
  <script src='http://cdn.evercam.io/js/v1/evercam.js'></script>
</head>
<body>
  <img evercam='dublin-rememberance-floor2' width="100%" height="100%" refresh='2000' />
</body>
</html>

Via JavaScript

Load camera image into jQuery selector by calling evercam method with ‘snapshot’ as first argument and options dictionary as second.

$(img).evercam('snapshot', {
  name: name,
  refresh: refreshRate
});

Following code will get new snapshot from camera every 5 seconds and display it as 320x240 pixels image:

$(img).evercam('snapshot', {
  name: 'dublin-rememberance-floor2',
  refresh: 5000
}).width(320).height(240);

Test API credentials

GET /test.{format}

User's cameras

GET /users/{id}/cameras.{format}

Create account

POST /users.{format}

Rights list

GET /users/{id}/rights.{format}

User info

GET /users/{id}.{format}

Update account

PATCH /users/{id}.{format}

User credentials

GET /users/{id}/credentials.{format}

Delete account

DELETE /users/{id}.{format}

GET /users/{id}/cameras.{format}

Returns the set of cameras owned by a particular user

Path variables

id

string required

Responses

200 OK

Body

Evercam::Presenters::Camera

POST /users.{format}

Starts the new user signup process

Request parameters

forename

string required

Forename.

lastname

string required

Lastname.

username

string required

Username.

country

string required

Country.

email

string required

Email.

password

string required

Password.

Responses

200 OK

Body

Evercam::Presenters::User

GET /users/{id}/rights.{format}

Returns the set of camera and other rights you have granted and have been granted (COMING SOON)

Path variables

id

string required

Responses

200 OK

GET /users/{id}.{format}

Returns available information for the user

Path variables

id

string required

Responses

200 OK

PATCH /users/{id}.{format}

Updates full or partial data on your existing user account

Path variables

id

string required

Username.

Request parameters

forename

string optional

Forename.

lastname

string optional

Lastname.

username

string optional

Username.

country

string optional

Country.

email

string optional

Email.

Responses

200 OK

Body

Evercam::Presenters::User

GET /users/{id}/credentials.{format}

Fetch API credentials for an authenticated user.

Path variables

id

string required

User name for the user to fetch credentials for.

Request parameters

password

string required

Password for the user to fetch credentials for.

Responses

200 OK

DELETE /users/{id}.{format}

Delete your account, any cameras you own and all stored media

Path variables

id

string required

Responses

200 OK

Body

Evercam::Presenters::User

Test camera params

GET /cameras/test.{format}

Camera information

GET /cameras/{id}.{format}

Update camera

PATCH /cameras/{id}.{format}

New camera

POST /cameras.{format}

Delete camera

DELETE /cameras/{id}.{format}

List shares

GET /cameras/{id}/shares.{format}

New share

POST /cameras/{id}/share.{format}

Delete share

DELETE /cameras/{id}/share.{format}

Update share

PATCH /cameras/share/{id}.{format}

List snapshots

GET /cameras/{id}/snapshots.{format}

Create a snapshot

POST /cameras/{id}/snapshots.{format}

Get latest snapshot

GET /cameras/{id}/snapshots/latest.{format}

Filter snapshots

GET /cameras/{id}/snapshots/range.{format}

Get days with snapshots

GET /cameras/{id}/snapshots/{year}/{month}/days.{format}

Get hours in a day with snapshots

GET /cameras/{id}/snapshots/{year}/{month}/{day}/hours.{format}

Get closest snapshot

GET /cameras/{id}/snapshots/{timestamp}.{format}

Save snapshot

POST /cameras/{id}/snapshots/{timestamp}.{format}

Delete snapshot

DELETE /cameras/{id}/snapshots/{timestamp}.{format}

Get JPG

GET /cameras/{id}/snapshot.jpg.{format}

GET /cameras/test.{format}

Tests if given camera parameters are correct

Request parameters

external_url

string required

External camera url.

jpg_url

string required

Snapshot url.

cam_username

string required

Camera username.

cam_password

string required

Camera password.

Responses

200 OK

Body

Evercam::Presenters::Camera

GET /cameras/{id}.{format}

Returns all data for a given camera

Path variables

id

string required

Responses

200 OK

Body

Evercam::Presenters::Camera

PATCH /cameras/{id}.{format}

Updates full or partial data for an existing camera

Path variables

id

string required

Camera Id.

Request parameters

name

string optional

Camera name.

is_public

unknown optional

Is camera public?

external_host

string optional

External camera host.

internal_host

string optional

Internal camera host.

external_http_port

string optional

External camera http port.

internal_http_port

string optional

Internal camera http port.

external_rtsp_port

string optional

External camera rtsp port.

internal_rtsp_port

string optional

Internal camera rtsp port.

jpg_url

string optional

Snapshot url.

cam_username

string optional

Camera username.

cam_password

string optional

Camera password.

Responses

200 OK

Body

Evercam::Presenters::Camera

POST /cameras.{format}

Creates a new camera owned by the authenticating user

Request parameters

id

string required

Camera Id.

name

string required

Camera name.

is_public

unknown required

Is camera public?

external_host

string optional

External camera host.

internal_host

string optional

Internal camera host.

external_http_port

number optional

External camera http port.

internal_http_port

number optional

Internal camera http port.

external_rtsp_port

number optional

External camera rtsp port.

internal_rtsp_port

number optional

Internal camera rtsp port.

jpg_url

string optional

Snapshot url.

cam_username

string optional

Camera username.

cam_password

string optional

Camera password.

Responses

200 OK

Body

Evercam::Presenters::Camera

DELETE /cameras/{id}.{format}

Deletes a camera from Evercam along with any stored media

Path variables

id

string required

Responses

200 OK

Body

Evercam::Presenters::Camera

GET /cameras/{id}/shares.{format}

Get the list of shares for a specified camera

Path variables

id

string required

The unique identifier for a camera.

Responses

200 OK

Body

Evercam::Presenters::CameraShare

POST /cameras/{id}/share.{format}

Create a new camera share

Path variables

id

string required

Request parameters

email

string required

Email address of user to share the camera with.

rights

string required

A comma separate list of the rights to be granted with the share.

message

string optional

Not currently used.

String

string optional

Not currently used.

notify

unknown optional

Not currently used.

Responses

200 OK

Body

Evercam::Presenters::CameraShare

DELETE /cameras/{id}/share.{format}

Delete an existing camera share

Path variables

id

string required

The unique identifier for a camera.

Request parameters

share_id

number required

The unique identifier of the share to be deleted.

Responses

200 OK

PATCH /cameras/share/{id}.{format}

Update an existing camera share (COMING SOON)

Path variables

id

string required

Responses

200 OK

GET /cameras/{id}/snapshots.{format}

Returns the list of all snapshots currently stored for this camera

Path variables

id

string required

Camera Id.

Responses

200 OK

POST /cameras/{id}/snapshots.{format}

Fetches a snapshot from the camera and stores it using the current timestamp

Path variables

id

string required

Camera Id.

Request parameters

notes

string optional

Optional text note for this snapshot

Responses

200 OK

GET /cameras/{id}/snapshots/latest.{format}

Returns latest snapshot stored for this camera

Path variables

id

string required

Camera Id.

Request parameters

with_data

unknown optional

Should it send image data?

Responses

200 OK

Body

Evercam::Presenters::Snapshot

GET /cameras/{id}/snapshots/range.{format}

Returns list of snapshots between two timestamps

Path variables

id

string required

Camera Id.

Request parameters

from

number required

From Unix timestamp.

to

number required

To Unix timestamp.

with_data

unknown optional

Should it send image data?

limit

number optional

Limit number of results, default 100 with no data, 10 with data

page

number optional

Page number

Responses

200 OK

GET /cameras/{id}/snapshots/{year}/{month}/days.{format}

Returns list of specific days in a given month which contains any snapshots

Path variables

id

string required

Camera Id.

year

number required

Year, for example 2013

month

number required

Month, for example 11

Responses

200 OK

GET /cameras/{id}/snapshots/{year}/{month}/{day}/hours.{format}

Returns list of specific hours in a given day which contains any snapshots

Path variables

id

string required

Camera Id.

year

number required

Year, for example 2013

month

number required

Month, for example 11

day

number required

Day, for example 17

Responses

200 OK

GET /cameras/{id}/snapshots/{timestamp}.{format}

Returns the snapshot stored for this camera closest to the given timestamp

Path variables

id

string required

Camera Id.

timestamp

number required

Snapshot Unix timestamp.

Request parameters

with_data

unknown optional

Should it send image data?

range

number optional

Time range in seconds around specified timestamp

Responses

200 OK

Body

Evercam::Presenters::Snapshot

POST /cameras/{id}/snapshots/{timestamp}.{format}

Stores the supplied snapshot image data for the given timestamp

Path variables

id

string required

Camera Id.

timestamp

number required

Snapshot Unix timestamp.

Request parameters

data

unknown required

Image file.

notes

string optional

Optional text note for this snapshot

Responses

200 OK

DELETE /cameras/{id}/snapshots/{timestamp}.{format}

Deletes any snapshot for this camera which exactly matches the timestamp

Path variables

id

string required

Camera Id.

timestamp

number required

Snapshot Unix timestamp.

Responses

200 OK

GET /cameras/{id}/snapshot.jpg.{format}

Returns jpg from the camera

Path variables

id

string required

Camera Id.

Responses

200 OK

Supported camera vendors

GET /models.{format}

Vendor's models

GET /models/{vendor}.{format}

Camera info

GET /models/{vendor}/{model}.{format}

GET /models.{format}

Returns set of support supported camera vendors

Responses

200 OK

Body

Evercam::Presenters::Vendor

GET /models/{vendor}.{format}

Returns set of known models for a supported camera vendor

Path variables

vendor

string required

Responses

200 OK

Body

Evercam::Presenters::Vendor

GET /models/{vendor}/{model}.{format}

Returns data for a particular camera model

Path variables

vendor

string required

model

string required

Responses

200 OK

Body

Evercam::Presenters::Model

List all vendors

GET /vendors.{format}

Filter vendors

GET /vendors/{mac}.{format}

GET /vendors.{format}

Returns all known IP hardware vendors

Responses

200 OK

Body

Evercam::Presenters::Vendor

GET /vendors/{mac}.{format}

Returns all known IP hardware vendors filtered by MAC prefix

Path variables

mac

string required

Responses

200 OK

Body

Evercam::Presenters::Vendor

GET /test.{format}

A simple endpoint that can be used to test whether an API id and key pair are valid.

Request parameters

api_id

string optional

The API id to be tested.

api_key

string optional

The API key to be tested.

Responses

200 OK

Object

id

string

Unique Evercam identifier for the camera

name

string

Human readable or friendly name for the camera

owner

string

Username of camera owner

vendor

string

Unique identifier for the camera vendor

model

string

Name of the camera model

created_at

number

Unix timestamp at creation

updated_at

number

Unix timestamp at last update

last_polled_at

number

Unix timestamp at last heartbeat poll

last_online_at

number

Unix timestamp of the last successful heartbeat of the camera

timezone

string

Name of the IANA/tz timezone where this camera is located

is_online

boolean

Whether or not this camera is currently online

is_public

boolean

Whether or not this camera is publically available

external_host

string

External host of the camera

internal_host

string

Internal host of the camera

external_http_port

number

External http port of the camera

internal_http_port

number

Internal http port of the camera

external_rtsp_port

number

Internal rtsp port of the camera

internal_rtsp_port

number

External rtsp port of the camera

jpg_url

string

Snapshot url

cam_username

string

Camera username

cam_password

string

Camera password

mac_address

string

The physical network MAC address of the camera

location

unknown

GPS lng and lat coordinates of the camera location

Methods: Camera information Delete camera New camera Test camera params Update camera User's cameras

Object

id

string

Unique Evercam username

created_at

number

Unix timestamp at creation

updated_at

number

Unix timestamp at last update

confirmed_at

number

Unix timestamp at account confirmation

forename

string

Users forename

lastname

string

Users lastname

username

string

Unique Evercam username

email

string

Users email address

country

string

Two letter ISO country code

Methods: Create account Delete account Update account

Object

id

string

Unique identifier for the vendor

name

string

Name of the vendor

known_macs

Array of string

String array of MAC prefixes the vendor uses

is_supported

boolean

Whether or not this vendor produces Evercam supported cameras

models

Array of string

String array of models currently known for this vendor

Methods: Filter vendors List all vendors Supported camera vendors Vendor's models

Object

vendor

string

Unique identifier for the vendor

name

string

Name of the model

known_models

Array of string

String array of all models known to share the same defaults

defaults

unknown

Various default values used by this camera model

Methods: Camera info

Object

id

number

Unique identifier for a camera share.

camera_id

string

Unique identifier of the shared camera.

user_id

number

Unique user id of the user the camera is shared with.

email

string

The email address of the user the camera is shared with.

kind

string

Either ‘public’ or ‘private’ depending on the share kind.

rights

string

A comma separated list of the rights available on the share.

Methods: List shares New share

Object

camera

string

Unique Evercam identifier for the camera

notes

string

Note for snapshot

created_at

number

Snapshot timestamp

timezone

string

Name of the IANA/tz timezone where this camera is located

data

unknown

Image data

Methods: Get closest snapshot Get latest snapshot