Introduction

HerdEye provides a simple and powerful API to integrate information and live video from the farm into your business or application.

This API reference provides information on available endpoints and how to interact with them.

To access the API you will require a key. Keys can be obtained by emailing developers@herdeye.ie.

Authentication

curl "https://api.herdeye.ie"
  -H "Authorization: Bearer YOUR-API-KEY"

const herdeye = require("herdeye")("YOUR-API-KEY");

To access the API you will require a key. Keys can be obtained by emailing developers@herdeye.ie.

Your API key is required for all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR-API-KEY

You must replace YOUR-API-KEY with your personal API key.

Cameras

The Camera Object

{
  "id": "cam_e0ac3a8316c4",
  "active": true,
  "ip": "192.168.12.22",
  "format": "h264", 
  "hecu": "hecu_d19a4ff3a682"
}

This endpoint will give metadata on any of the connected cameras to a users account.

A person can have many cameras assigned to their account and cameras can be shared over many accounts.

Each camera produces notifications. It also may produce information about the current scene.

Object Properties

Parameter	Description
id	A globally unique identifer for this camera.
active	true if the camera is up and connected to HerdEye.
ip	the internal IP address the HECU is using to connect to the camera
format	the video format the camera is producing
hecu	the identifier for the HerdEye Compute Unit the camera is connected to

List All Cameras

curl "https://api.herdeye.ie/cameras"
  -H "Authorization: Bearer YOUR-API-KEY"

const herdeye = require("herdeye")("YOUR-API-KEY");

let cameras = herdeye.cameras.list();

Fetch all the cameras your account has access to

HTTP Request

GET https://api.herdeye.com/cameras

Get a Camera

curl "https://api.herdeye.ie/cameras/cam_e0ac3a8316c4"
  -H "Authorization: Bearer YOUR-API-KEY"

const herdeye = require("herdeye")("YOUR-API-KEY");

let camera = herdeye.cameras.get("cam_e0ac3a8316c4");

Fetch just a specific camera instance

HTTP Request

GET https://api.herdeye.com/cameras/{ID}

URL Parameters

Parameter	Description
ID	The ID of the camera to retrieve

Notifications

The Notification Object

{
  "id": "nfn_f74bb4d104b6",
  "camera": "cam_e0ac3a8316c4",
  "hecu": "hecu_d19a4ff3a682",
  "time": "2019-10-04T13:00:18.922Z",
  "point": {
    "x": 0.482,
    "y": 0.195
  },
  "snapshot": "cdn.herdeye.ie/notifications/nfn_f74bb4d104b6.jpg",
  "description": "Labour has begun",
  "importance": 2
}

Notifications are events that HerdEye has detected.

Object Properties

Parameter	Description
id	A globally unique identifer for this notification.
camera	the ID of the camera that observed the event
hecu	the identifier for the HerdEye Compute Unit the camera is connected to
time	An ISO 8601 date string marking when the event happened.
point	The relative x,y coordinate on the video image where the event occured.
snapshot	The url for an image of what happened.
description	A string stating what was observed
importance	A value given to how interesting the notification is. 0 = Low, 1 = Med, 2 = High

List Notifications

curl "https://api.herdeye.ie/notifications?limit=10&created_after=2019-11-05T10:00:00.000Z&camera=cam_e0ac3a8316c4"
  -H "Authorization: Bearer YOUR-API-KEY"

let notifications = herdeye.notifications.list({
  limit: 10,
  time: "2019-11-05T10:00:00.000Z",
  camera: "cam_e0ac3a8316c4"
});

Retrieve all the notifications.

Parameters

Parameter	Description
limit	Limit the number of results returned. Max 100, default 10. (optional)
time	A filter on the list based on the objects `time` field. Will return results after the supplied time. (optional)
camera	Filter the list to only return notifications from a specific camera. If omitted notifications for all cameras on the account are returned.

HTTP Request

GET https://api.herdeye.com/cameras

Snapshots

Often it can be useful to show a preview before showing live video. For that instance you can load a snapshot.

Snapshots display a relatively recent image from the camera. It is important to note that this image may not be live.

Get a recent image


curl "https://cdn.herdeye.com/snapshots/cam_e0ac3a8316c4" > "my_snapshot.jpg"


let imageURL = "https://cdn.herdeye.com/snapshots/cam_e0ac3a8316c4.jpg"

Substitute the ID for the camera into the following URL

https://cdn.herdeye.com/snapshots/{Camera_ID}

Video

Video can be streamed live from a connected camera into any modern browser.

Opening the video URL will load a video player which can be embedded into any page using an iframe. It is not possible currently to access the stream directly.

Watching from a browser

let videoUrl = herdeye.video.url("cam_e0ac3a8316c4");
// videoUrl can now be used as the source for an iframe

The camera's video can be streamed into a browser by following the URL:

https://video.herdeye.com/cameras/{ID}

Webhooks

Instead of polling for new notifications we recommend instead using webhooks.

When a new notification arrives an HTTP POST request will be sent to the URL you supply. The body of the request will have the notification formatted in JSON.

The webhook object

{
  "id": "wh_3a9iie30",
  "url": "https://example.com/my/webhook/endpoint"
}

Object Properties

Parameter	Description
id	A globally unique identifer.
url	The URL of the webhook endpoint.

Create a webhook

curl "https://api.herdeye.ie/webhooks"
  -H "Authorization: Bearer YOUR-API-KEY"
  -d url="https://example.com/my/webhook/endpoint"

herdeye.webhooks.create({
  url: "https://example.com/my/webhook/endpoint"
});

Supply the url of your webhook endpoint.

HTTP Request

POST https://api.herdeye.com/webhooks

Delete a webook

curl "https://api.herdeye.ie/webooks/wh_3a9iie30"
  -H "Authorization: Bearer YOUR-API-KEY"
  -X DELETE

herdeye.webhooks.delete("wh_3a9iie30");

To remove a previously created webhook.

HTTP Request

DELETE https://api.herdeye.com/webhooks/{ID}

List all webhooks

curl "https://api.herdeye.ie/webooks"
  -H "Authorization: Bearer YOUR-API-KEY"

herdeye.webhooks.list();

Returns all the webhooks setup on your account.

HTTP Request

GET https://api.herdeye.com/webooks