NAV Navbar
Logo

Welcome

The Camio API makes it simple to add real-time video search to any camera, NVR, VMS, website or service. Also see ifttt.com/camio for ways that non-programmers can script Camio’s interaction with other services. Please let us know how we can improve either this documentation or the Camio API itself. Thanks.

Root Endpoint

The root API endpoint for all API commands is:

https://camio.com/api

All timestamps use the ISO8601 format:

YYYY-MM-DDTHH:MM:SS.mmmZ like 2016-01-21T20:38:31.469-0700

The Basics

Most developers want a quick way to record video, perform an action when something important happens, and see what’s recorded. So here’s a quick intro to those three uses of the Camio API.

Recording Video and Images

Example requests to record video and images:

curl \
    -H "Content-Type: video/mp4" \
    -X PUT \
    -T "2014-07-21T20:38:31.000-07:00.mp4" \
    https://camio.com/api/users/51r6kndapc/cameras/front/content/2014-07-21T20:38:31.000-07:00.mp4?camera_id=1234&upload_mode=video
curl \
    -H "Content-Type: image/jpeg" \
    -X PUT \
    -T "2014-07-21T20:38:32.183-07:00.jpeg" \
    https://camio.com/api/users/51r6kndapc/cameras/front/content/2014-07-21T20:38:32.183-07:00.jpeg?camera_id=1234

You can record with any network camera using camio.com/start.

But you can also programmatically connect any other source of video/images using the API to upload camera content. For example, the command on the right uploads a motion-triggered snapshot to a camera named front using the Upload Token 51r6kndapc.

Note that no Authorization HTTP Header is needed. Your Upload Token itself grants permission to upload only - without granting permission to access content.

These examples upload directly to the cloud, however Camio Box is the bandwidth-efficient way to ingest video, because the video can be analyzed on your local network before deciding whether and how to upload it. Download Camio Box VM for free, and use its POST /api/content API locally instead.

Registering Callbacks

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"callback_url": "http://example.com/camio/package-delivery", "type": "query_match", "query": {"text": "people approaching mailbox in front"}}' \
    -X POST https://camio.com/api/users/me/hooks

Hooks enable you to take an action whenever particular events happen. For example, use the curl command on the right to create a hook requesting that:

Seeing Recorded Content

An example of an iframe:

<iframe src="https://camio.com/c/b1bqks3l76yo&key=123abc" width="603" height="452" frameBorder="0"></iframe>

You can use the Camio Browser, iOS, and Android apps to view recorded content, or you can write your own viewers using the low-level Search API. But if you’d like to embed content on your site easily, you can use an iframe as in this example of the mischievous dog Kody:

HTML

<iframe src="https://camio.com/c/:view_token&key=:key" width="603" height="452" frameBorder="0"></iframe>

URL Parameters

Name Description Details
view_token The view token that authorizes access to the Camio string, required, example: b1bqks3l76yo
key Your Camio API Key. All requests must include your API Key as the value of the key parameter so that Camio can contact you about your website/application usage if necessary string, required, example: 123abc

Authentication

OAuth

To authorize a cURL request, for example, use this code:

# With cURL, you can just pass the correct header with each request
curl "https://camio.com/api/users/me/cameras" \
    -H "Authorization: token OAUTH-TOKEN"

Be sure to replace OAUTH-TOKEN with your OAuth token.

Camio uses OAuth tokens to provide access to the API.

You can obtain a development OAuth token by using the Generate button at https://camio.com/settings/integrations/#api.

Authorization Header

Camio expects the token to be included in all API requests to the server in an HTTP header like:

Authorization: token OAUTH-TOKEN

Authorization Parameter

The Authorization Header is the preferred method of authentication with an OAuth token. But alternatively, the access_token query parameter can specify the OAuth token.

https://camio.com/api/search/?text=Entry&access_token=OAUTH-TOKEN

Developer OAuth Token

Your application normally obtains the value for OAUTH-TOKEN from the user’s granting permission via the OAuth flow. For initial development, you can replace OAUTH-TOKEN with your Developer OAuth token.

How to obtain and OAuth Token

Redirect users to request Camio access

GET https://camio.com/api/login/oauth/authorize

URL Parameters
Name Description Details
client_id The client id you received from Camio. string, required, example: abc123
redirect_uri The URL in your app where users will be sent after authorization. This url must accept the query parameter &code=:code. string, optional, example https://www.example.com/camio/oauth
scope Comma separated list of scopes. Default scope is user. string, optional.
state An unguessable random string. It is used to protect against cross-site request forgery attacks. string, optional.

Camio redirects back to your site

If the user accepts your request, Camio redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted. Exchange this for an access token with:

POST https://camio.com/api/login/oauth/access_token

URL Parameters
Name Description Details
client_id The client id you received from Camio. string, required, example: abcdefg
redirect_uri The URL in your app where users will be sent after authorization. This url must accept the query parameter &code=:code. string, optional, example https://www.example.com/oauth
client_secret The client secret you received from Camio when you registered. string, required.
code The code you received as a response to the prior step. string, required.
Response

By default, the response will take the following form: access_token=e72e16e429212e7710c838347ae178b4a&token_type=bearer

You can also receive the content in different formats depending on the Accept header: Accept: application/json {"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a","token_type":"bearer"}

Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user. Currently, you must supply the access token in the HTTP Authorization header for POST/PUT/PATCH commands. For HTTP GET commands, you can supply &access_token= as an url parameter.

For example, an HTTP POST would use: $ curl -H "Authorization: token abcdefg" https://camio.com/api/users/me/cameras

and an HTTP GET would use: GET https://www.camiolog.com/api/users/me/cameras?access_token=abcdefg

OAuth Scopes

Camio scopes are expressed as the object to which they grant access followed by the class of actions they allow (e.g. settings:write). If the class of action is omittted, then the scope is for all actions on the object.

There are currently only two classes of actions:

  1. read: Reading the full information about a single resource.
  2. write: Modifying the resource in any way e.g. creating, editing, or deleting.
Scope Description
user full access to act as the user.
settings read and write access to all settings.
settings:write write access to all settings.
setttings:read read access to all settings.
settings:recording read and write access to turn recording ON/OFF.
settings:recording:write write access to turn recording ON/OFF.
settings:recording:read read access to recording ON/OFF.

If your application requires some other scope, just let us know.

Upload Token

You can also upload content without using OAuth by using your Upload Token instead (found on the page camio.com/token). An Upload Token permits only the uploading of content to your account - without any permission to access your account. That way, the camera source itself has no sign-in credentials on it.

Cameras

Camio really thinks of a “camera” simply as a video stream. For example, in addition to standalone IP cameras, a “camera” may also be an NVR/VMS channel or a sequence of imported video files.

List all Cameras

The JSON response is:

[
    {
        "name": "Chrome",
        "attribution": {},
        "tags": [],
        "refreshInterval": 0,
        "camera_id": "ET22dbt2iGBzsaN4u",
        "is_online": true,
        "capabilities":["web_rtc","audio","video"]
    },
    {
        "name": "front",
        "attribution": {},
        "tags": [],
        "is_online": false,
        "capabilities":[]
    },
    {
        "name": "iPad",
        "attribution": {},
        "camera_id":"YY271ZZZ0128XXX",
        "is_online": true,
        "capabilities":["web_rtc","audio","video"]
    }
]

Lists all of the cameras connected to an account.

HTTP Request

GET https://camio.com/api/users/me/cameras/

Query Parameters

Name Description Details
fetch_zones true if you wish to recieve a list of camera zones along with each camera. string, optional, example: true
user The email address of the host account that the camera are to be fetched for. string, optional, example: test@example.com

The boolean field is_online in each Camera object returned, is used to indicate whether the camera is considered to be online by the server or not. The server’s determination of online status takes into account state polls as well as recent uploads. Only the field name is guaranteed to be included with each Camera object returned by the API.

Get Camera

The JSON response is:

{
    "camera_id": "2431614740321587915",
    "attribution": {},
    "capabilities": [
        "web_rtc",
        "audio",
        "video",
        "per_camera_settings",
        "name_changeability"
    ],
    "is_online": true,
    "latitude": 0.0,
    "longitude": 0.0,
    "name": "Door",
    "resolution": {
        "aspect_ratio": 1.7777778,
        "height": 720,
        "width": 1280
    },
    "session_id": "-MTBMEl-fg",
    "tags": [],
    "user_id": "xyzpdq0798386757677"
}

HTTP Request

GET https://camio.com/api/users/me/cameras/:camera

URL Parameters

Name Description Details
camera The name of the camera. string, required, example: front

The boolean field is_online in the Camera object returned is used to indicate whether the camera is considered to be online by the server or not. The server’s determination of online status takes into account state polls as well as recent uploads. The resolution of the camera is known only after the camera has uploaded content.

Create Camera

An example request is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{}' \
    -X POST https://camio.com/api/cameras/discovered

An example JSON payload for the request is:

{
    "0123456789AB.0": {
        "actual_values": {
            "password": {
                "is_multiselect": false,
                "options": [
                    {
                        "name": "opensesame",
                        "value": "opensesame"
                    }
                ]
            }
        },
        "default_values": {
            "password": {
                "is_multiselect": false,
                "options": [
                    {
                        "name": "admin",
                        "value": "admin"
                    }
                ]
            },
            "stream": {
                "is_multiselect": true,
                "options": [
                    {
                        "name": "Channel 1",
                        "value": "1"
                    },
                    {
                        "name": "Channel 2",
                        "value": "2"
                    }                       
                ]
            },
            "username": {
                "is_multiselect": false,
                "options": [
                    {
                        "name": "admin",
                        "value": "admin"
                    }
                ]
            }
        },
        "device_id": "d123abc",
        "ip_address": "192.168.1.23",
        "mac_address": "0123456789AB",
        "maker": "Sharx",
        "model": "SCNC3905",
        "rtsp_server": "rtsp://:@:"
        "rtsp_path": "/live//h264.sdp",
        "should_config": true
    }
}

This API endpoint is for creating cameras that are connected to Camio via camio.com/box only.

To create a camera, specify the way to obtain its video. Camio works with any H.264 video stream from any camera, DVR, NVR, or VMS. There are two methods of acquiring video (aka acquisition_method):

  1. rtsp: the live rtsp video stream is processed in real-time.
  2. batch: video files are processed in bulk as files.

HTTP Request

POST https://camio.com/api/cameras/discovered

FYI, the POST behaves like a PATCH for the convenience of updating the camera using partially complete information.

JSON Payload

The POST payload is a dictionary keyed by the local_camera_id that the caller assigns to each camera. The required device_id value is obtained from having registered a Camio Box.

The required fields differ based on the value of acquisition_method.

Required fields for "acquisition_method": "rtsp"

Name Description Details
device_id The device_id of the Camio Box through which this camera is connected to Camio. string, required.
local_camera_id Supplied as a key value in the dictionary, this is the arbitrary and unique id chosen by the caller. It is unique among the caller’s cameras but not necessarily globally unique across users. string, required.
rtsp_server The server of the H.264 RTSP stream. string, required for rtsp, example: rtsp://:@:
rtsp_path The path to the specific stream on the server. string, required for rtsp, example: /live//h264.sdp
mac_address The MAC address of the camera, which is used by Box to update the camera’s ip_address as it changes due to DHCP assigments. string, required for rtsp.
ip_address The ip_address of the camera video source. string, required for rtsp.

Required fields for "acquisition_method": "batch"

Name Description Details
device_id The device_id of the Camio Box through which this camera is connected to Camio. string, required.
local_camera_id Supplied as a key value in the dictionary, this is the arbitrary and unique id chosen by the caller. It is unique among the caller’s cameras but not necessarily globally unique across users. string, required.
acquisition_method The value batch, which informs the Camio Box associated with device_id to expect video files POSTed string, required.
mac_address TO BE REFACTORED AS OPTIONAL; DUMMY VALUE IS OK FOR NOW string, required (TEMPORARILY).

Common fields (regardless of value of acquisition_method)

Name Description Details
actual_values The dictionary of variable values to be used for mustache template substitutions. string, required if any fields rely on mustache variables.
default_values The dictionary of default variable values to be used in the absence of a value supplied in actual_values. string, required if any fields rely on mustache variables.
should_config TO BE REFACTORED, but currently true to connect the camera to the device_id and false to disconnect it. boolean, required.

Delete Camera

The response is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/users/me/cameras/:camera

URL Parameters

Name Description Details
camera The name of the camera. string, required, example: front

Labels

List Camera Labels

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/cameras/labels

The JSON response is:

{
    "Front Door": [
        "California",
        "home",
        "94401",
        "San Mateo"
    ],
    "Office Entrance": [
        "California",
        "work",
        "94043",
        "Mountain View"
    ]
}

Retrieve the dictionary of camera labels keyed by camera_name. If a particular camera_name is supplied as an URL Parameter, then the response is the array of labels for that camera_name only.

URL Parameters

Name Description Details
user The email address of the account owning the camera string, optional, example: test@example.com
camera_name The name of a particular camera if only one camera requested string, optional, example: Front Door

Add Camera Labels

An example request is:

curl \
    -H "Authorization: token abc123" \
    -d '{"Front Door": ["home", "San Mateo"], "Office Entrance":["work"]}' \
    -X POST \
    https://camio.com/api/cameras/labels

The response is:

204 (No Content)

Add the argument camera labels to any existing labels associated with the camera(s). The input JSON is a dictionary keyed by camera_name with values of an array of labels.

URL Parameters

Name Description Details
user The email address of the account owning the camera string, optional, example: test@example.com

Replace Camera Labels

An example request is:

curl \
    -H "Authorization: token abc123" \
    -d '{"Front Door": ["home", "San Mateo"], "Office Entrance":["work"]}' \
    -X PUT \
    https://camio.com/api/cameras/labels

The response is:

204 (No Content)

Use PUT to replace the camera labels with those specified by the JSON payload, which is a dictionary keyed by camera_name with values of an array of labels.

URL Parameters

Name Description Details
user The email address of the account owning the camera string, optional, example: test@example.com

Zones

List all Zones

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/users/me/cameras/Office/zones

The JSON response is:

[
  {
    "name": "door",
    "polygons": [
      {
        "points": [
          {
            "x": 0.12079093470323,
            "y": 0.16636921918746
          },
          ...
        ]
      }
    ]
  },
  {
    "name": "entrance",
    "polygons": [
      {
        "points": [
          {
            "x": 0.45530391629449,
            "y": 0.1171216887084
          },
          ...
        ]
      }
    ]
  }
]

Retrive a list of all of the zones including their names and the polygons that define them for a specific camera.

HTTP Request

GET https://camio.com/api/users/me/cameras/:camera/zones

URL Parameters

Name Description Details
camera The name of the camera. string, required, example: front

Get Specific Zone

The JSON response is:

{
    "name": "door",
    "polygons": [
      {
        "points": [
          {
            "x": 0.12079093470323,
            "y": 0.16636921918746
          },
          ...
        ]
      }
    ]
}

HTTP Request

GET https://camio.com/api/users/me/cameras/:camera/zones/:zone

URL Parameters

Name Description Details
camera The name of the camera. string, required, example: front
zone The name of the zone. string, required, example: door

Create or Edit Zone

The JSON request body is:

{
    "name": "door",
    "polygons": [
      {
        "points": [
          {
            "x": 0.12079093470323,
            "y": 0.16636921918746
          },
          ...
        ]
      }
    ]
}

HTTP Request

POST https://camio.com/api/users/me/cameras/:camera/zones/:zone

URL Parameters

Name Description Details
camera The name of the camera. string, required, example: front
zone The name of the zone. string, required, example: door

Delete Zone

The response is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/users/me/cameras/:camera/zones/:zone

URL Parameters

Name Description Details
camera The name of the camera. string, required, example: front
zone The name of the zone. string, required, example: door

Hooks

Hooks enable services to be notified of events observed by Camio to take action on them.

For example, you may want to text the on-duty security guard whenever a person approaches a side alley between 2am and 5am, or you may want to perform additional image analysis whenever there are people detected in an event.

Hook Types

Type Description
query_match an event matches the hook’s query.
power_disconnected a camera loses its A/C power connection.
job_completed a Job has completed execution.

List all Hooks

The curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/me/hooks

The JSON response is:

[
  {
    "id": "1",
    "type": "query_match",
    "callback_url": "https://example.com/camio/delivery",
    "callback_payload_type": "notification",
    "query": "front people in blue approaching mailbox"
  },
  {
    "id": "2",
    "type": "query_match",
    "callback_url": "https://example.com/camio/dog-walker",
    "callback_payload_type": "notification",
    "query": "people approaching dogbed"
  }
]

HTTP Request

GET https://camio.com/api/users/me/hooks

Get Specific Hook

The curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/me/hooks/1

The JSON response is:

{
  "id": "1",
  "type": "query_match",  
  "callback_url": "https://example.com/camio/delivery",
  "callback_payload_type": "notification",
  "query": "people in blue approaching mailbox"
}

HTTP Request

GET https://camio.com/api/users/me/hooks/:hook

URL Parameters

Name Description Details
hook The id of the Hook string, required, example: 1

Create Hook

The curl command is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"callback_url": "http://example.com/camio/package-delivery", "type": "query_match", "query": "people in blue approaching mailbox at front gate", "callback_payload_type": "notification",}' \
    -X POST https://camio.com/api/users/me/hooks

The JSON response is:

{
  "id": "1",
  "type": "query_match",
  "callback_url": "https://example.com/camio/package-delivery",
  "callback_payload_type": "notification",
  "query": "people in blude approaching mailbox at front gate",
}

The command on the right creates a new hook requesting that:

The json payload in the POST to the callback_url describes the event that triggered the Hook and includes the requested type of payload content.

HTTP Request

POST https://camio.com/api/users/me/hooks

Body

Name Description Details
type The event type that triggers the hook’s callback. string, required, example: query_match
callback_url The URL that receives the POST to process the callback payload string, required, example: https://example.com/camio/package-delivery
callback_payload_type The type of content included in the payload that’s sent to the callback_url. See callback_payload_type string, required, analysis or notification.
query The query text (as you’d enter it into the Camio search box) whose conditions must be matched in order to trigger the hook callback. string, required unless parsed_query was specified, example: “people in blue approaching mailbox at front gate”
parsed_query The exact conditional expression that filters which Events trigger the hook callback. See parsed_query conditions below. string, optional, example: “camera == ‘front’ and (‘_color_blue’ in labels and ‘_ml_human’ in labels and ‘mailbox’ in labels and ‘gate’ in labels)”
client_metadata Optional, arbitrary json metadata that will be included in the payload sent to the callback_url. string, optional, example: {"user_id":"xyz"}

Hook Callback Payload Types

The payload send to the callback_url is determined by the value of callback_payload_type.

Type Description
analysis include representative snapshot images, video and metadata to be used in further image analysis of the event.
notification include metadata that describes the event sufficiently for notifications to people, apps and services.

parsed_query conditions

It’s easier to supply query as the same text that you type into the search box. However, you can supply parsed_query instead if you want precise control over the interpretation without regard to the current state of the user’s account. For example, the parsing of the word garage in the query below is only known to be the name of camera when there is in fact a camera named “garage” in the user’s account. So in rare cases, when you want to create the Hook prior to the existence of a camera or zone defined by the user, then you can use parsed_query instead.

The parsed_query specifies the conditions of the filter and allows this subset of the Python conditional operators: and, or, not, in, <, <=, >, >=, ==, !=. The variables that can be referenced in the conditions include:

Variable Description
camera the name of the camera uploading the event
labels a list of labels already associated with the event
date the event start date as a python datetime object (date.year, date.day, etc are allowed).

For example, the query:

front and garage red or blue cars approaching

translates to the parsed_query:

(camera == "front" or camera == "garage") and (("_ml_approaching" in labels) and ("_ml_car" in labels) and ("_color_red" in labels or "_color_blue" in labels))

For “callback_payload_type” of “notification”, the JSON payload sent to the “callback_url” is:

{
  "hook_id": "1",
  "event": {
    "id": "abcdefghijklmnop",
    "source": "front",
    "earliest_date":"2015-05-21T02:07:44.636-0000",
    "latest_date":"2015-05-21T02:08:12.776-0000",
    "labels": ["mailbox", "_color_blue"]
  }
}

For “callback_payload_type” of “analysis”, the JSON payload sent to the “callback_url” is:

{
  "videos": [
    {
      "url": "https://storage.googleapis.com/camio_test/mv-109010...20-00166CF67F20.0_2017-07-07T20:27:57.355590_c75f3cb5-efd0-4bc4-87a0.mp4?Expires=1499462311&GoogleAccessId=397790679937%40developer.gserviceaccount.com&Signature=EtPRfbzP...FO%2BFeBk%3D", 
      "timestamp": {
        "meta_class": "datetime.datetime", 
        "date": "2017-07-07T20:27:57.355590"
      }, 
      "duration": 11.901999999999999, 
      "type": "video/mp4", 
      "id": "mv-109010...20-00166CF67F20.0_2017-07-07T20:27:57.355590_c75f3cb5-efd0-4bc4-87a0.mp4"
    }
  ], 
  "earliest_date": {
    "meta_class": "datetime.datetime", 
    "date": "2017-07-07T20:27:57.355590"
  }, 
  "labels": [], 
  "hook_id": "agxzfmNhbWlvLXRlc3RyEQsSBEhvb2s", 
  "images": [
    {
      "timestamp": "2017-07-07T20:28:03.306590", 
      "image_b64": "/9j/...Qf/2Q==", 
      "type": "image/jpeg", 
      "size": [
        376, 
        640
      ]
    }, 
    {
      "timestamp": "2017-07-07T20:27:59.339257", 
      "image_b64": "/9j/...//2Q==", 
      "type": "image/jpeg", 
      "size": [
        141, 
        240
      ]
    }, 
    {
      "timestamp": "2017-07-07T20:28:07.273923", 
      "image_b64": "/9j/...//Z", 
      "type": "image/jpeg", 
      "size": [
        141, 
        240
      ]
    }
  ], 
  "query": "1==1", 
  "latest_date": {
    "meta_class": "datetime.datetime", 
    "date": "2017-07-07T20:28:09.257590"
  }, 
  "user_id": "109010...20", 
  "event_id": "ev-109010...20-00166CF67F20.0_2017-07-07T20:28:18.440202_7d3721fe-5a06-47de-aa06.json", 
  "camera": "office_camera", 
  "aspect_ratio": 1.7021276595744681, 
  "callback_url": "https://camiologger.appspot.com/cam/hook/callback?certificate=FA5A313D1A572223E38...88B63C46EFA5D4235EAC927", 
  "client_metadata": null
}

Callback Payload

The json payload in the POST to the callback_url currently includes:

For example, if the hook created in the example above were triggered only by an event from the front camera when observing a USPS worker in a blue uniform, then the POST payload would include all the labels that were required by the hook and the additional label blue as in the example on the right.

Delete Hook

The response is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/users/me/hooks/:hook

URL Parameters

Name Description Details
hook The id of the hook. string, required, example: 1

Search

Search Video

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/search/?text=people+approaching+outdoor+walkway+7am+yesterday+in+sunglasses&num_results=50    

The JSON response is:

{
    "query": {
        "cameras": [
            "outdoor"
        ],
        "colors": [],
        "content_type": "image",
        "date": "2016-01-17T15:00:00.000-0000",
        "date_text_matched_lowercase": "7am yesterday",
        "earliest_date_considered": "2016-01-17T15:29:02.966-0000",
        "labels": [
            "_ml_approaching",
            "_ml_human",
            "walkway"
        ],
        "latest_date_considered": "2016-01-18T15:46:32.989-0000",
        "motion_type": "lmo",
        "object_type": "event",
        "remainder": "sunglasses",
        "sort": "asc",
        "text": "people approaching outdoor walkway 7am yesterday",
        "text_without_date_lowercase": "people approaching outdoor walkway",
        "user": "jcmaslan@gmail.com",
        "zones": [
            "walkway"
        ]
    },
    "result": {
        "bucket_type": "event",
        "buckets": [
            {
                "aspect_ratio": 1.3333334,
                "bucket_id": "ag1zfmNhbWlvbG9nZ2VyckYLEgVFdmVudCI7ZXY6MTE3NTUwMDAwNzk4Mzg2NzU3Njc3Om91dGRvb3I6MjAxNi0wMS0xN1QxNToyOTowMi45NjYwMDAM",
                "color": "#dadada",
                "count": 3,
                "cover_image_id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5If4nAkM",
                "earliest_date": "2016-01-17T15:29:02.966-0000",
                "images": [
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:02.966-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5POtgQgM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:03.836-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICwlKG_kwgM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:04.659-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5If4nAkM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    }
                ],
                "labels": [
                    "_color_black",
                    "_ml_human",
                    "_ml_approaching",
                    "walkway"
                ],
                "latest_date": "2016-01-17T15:29:04.659-0000",
                "max_interest_level": 3,
                "source": "outdoor"
            },
            {
                "aspect_ratio": 1.3333334,
                "bucket_id": "ag1zfmNhbWlvbG9nZ2VyckYLEgVFdmVudCI7ZXY6MTE3NTUwMDAwNzk4Mzg2NzU3Njc3Om91dGRvb3I6MjAxNi0wMS0xN1QxNToyOToxOC4xNTEwMDAM",
                "color": "#dadada",
                "count": 5,
                "cover_image_id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5M-yoAgM",
                "earliest_date": "2016-01-17T15:29:18.151-0000",
                "images": [
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:18.151-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5JuzjggM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:19.039-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5M-yoAgM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:19.783-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICwlPaxwAgM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    }
                ],
                "labels": [
                    "_color_brown",
                    "_ml_mail",
                    "walkway",
                    "_color_black",
                    "_ml_human",
                    "_ml_approaching"
                ],
                "latest_date": "2016-01-17T15:29:19.783-0000",
                "max_interest_level": 3,
                "source": "outdoor",
                "videos": [
                    {
                        "content_type": "video/mp4",
                        "date_created": "2016-01-17T15:29:33.387-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICwpJXY0QkM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "video/mp4",
                        "date_created": "2016-01-17T15:29:35.587-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICwpPvt3wkM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    }
                ]
            }
        ],
        "count": 26,
        "earliest_date_considered": "2016-01-17T15:29:02.966-0000",
        "latest_date_considered": "2016-01-18T15:46:32.989-0000",
        "more_results": true
    }
}

Search recorded content with plain text queries. The query parser understands camera names, dates, zones, colors, direction of movement, and other object labels.

HTTP Request

GET https://camio.com/api/search

Query Parameters

The text parameter is the preferred way to search. Camio parses the text into a query object that is returned in the response.

For “paginated” searches, specify the date and sort query parameters to continue fetching earlier or later results. For example, a sequence of requests to fetch 300 results starting at 8am from your camera named “front” would look like this:

  1. https://camio.com/api/search/?text=front+8am&num_results=100
  2. https://camio.com/api/search/?text=front+8am&sort=asc&num_results=100&date=2017-05-17T08%3A24%3A40.828-0700
  3. https://camio.com/api/search/?text=front+8am&sort=asc&num_results=100&date=2017-05-18T12%3A15%3A07.546-0700

In the example above, the date value for requests #2 and #3 is 1 millisecond later than the latest_date_considered found in the prior request’s result.

Name Description Details
text The query text that will be parsed to populate the Query object. Dates can be expressed in natural language or as precise ISO8601 strings. Use the v: operator to search with a view_token (e.g. front 8am v:vxy5q2). string, optional, example: people 6am to 8am
num_results The number of results to return. int, optional, default: 10, max: 100
date Filter date in ISO8601 format. string, optional, example: 2014-03-13T11:27:40.929-0000
sort Either asc or desc for date ascending or date descending order string, optional

Dates in query text

Camio interprets dates using Natural Language Processing and the current timezone of your browser. So here are examples of using dates and date ranges in the text parameter of an /api/search request assuming that you’re searching from Silicon Valley (Pacific Daylight Time) on May 17th, 2017:

text date values
8am to noon means earliest_date_allowed of 2017-05-17T15:00:00.000-0000 and latest_date_allowed of 2017-05-17T19:00:00.000-0000.
3 days ago at 3:30pm means date of 2017-05-14T22:30:00.000-0000.
Monday 2pm EDT means date of 2017-05-14T18:00:00.000-0000.

Colors in query text

The query parser currently matches only these colors: red, pink, brown, orange, yellow, green, cyan, blue, purple, magenta, white, gray, black

Directions of movement in query text

The query parser currently understands only two directions of movement: approaching, departing

Response JSON

The result is the important part of the response. However, the parsed query object is also included for future versions of /api/search and is derived from having parsed the text parameter of the request.

result

Name Description Details
bucket_type “event” is a video event of variable length up to 60 seconds long string
color The average color of the event to be used as placeholder until thumbnails have been fetched string, optional
count The number of results integer
earliest_date The earliest date contained in the bucket ISO8601 date string
latest_date The latest date contained in the bucket ISO8601 date string
source The camera name of the video source string, required
labels The indexed labels that describe color, direction of movement, objects, OCR text, etc… List of string
earliest_date_considered The earliest date examined by the server when searching ISO8601 date string
latest_date_considered The latest date examined by the server when searching ISO8601 date string
more_results false when the server is certain that there are no more results that will match the query
by trying an earlier date for a desc query or a later date for an asc query. boolean, required

query

Name Description Details
start_date The earliest date inclusive in ISO8601 format. string, optional, example: 2014-03-13T11:27:40.929-0000
end_date The latest date date inclusive ISO8601 format. string, optional, example: 2014-03-13T11:32:01.134-0000
events List of string Event ids to fetch. List. optional, used only for fetching an enumerated list of Events.
remainder The portion of the input Query.text that was unmatched by the parser. string, optional. For example, the query [backyard purple bucket] may have a Query.remainder of bucket if Camio’s query parser couldn’t match the word bucket with any object, camera, color, zone, label, direction of movement, etc…
cameras The list of camera matches that the parser found in the input text. List, optional.
zones The list of zone matches that the parser found in the input text. List, optional.
colors The list of color matches that the parser found in the input text. List, optional.
date_text_matched_lowercase The portion of the input text that was used to determine the date expression in the query. string, optional. For example the Query.text people approaching entrance last Friday 2pm would have Query.date_text_matched_lowercase last friday 2pm.
text_without_date_lowercase This value is just for the convenience of the call in avoiding the need to subtract the matched date text from the Query.text string, optional.
parsed_query The conditional expression derived from having parsed the input text. string.

Search Cameras

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/search/cameras?text=work

The JSON response is:

{
    "query": {
        "cameras": [
            "east",
            "Office",
            "west"
        ],
        "object_type": "camera",
        "parsed_query": "camera == \"east\" or camera == \"Office\" or camera == \"west\"",
        "remainder": "",
        "sort": "desc",
        "text": "work",
        "text_without_date_lowercase": "work",
        "user": "test@example.com",
        "view_tokens_text_matched": [],
    },
    "result": {
        "bucket_type": "camera",
        "buckets": [
            {
                "bucket_id": "user123456:00E04CC27CC5:00E04CC27CC5.0",
                "labels": [
                    "California",
                    "San Mateo",
                    "Work",
                    "94401"
                ],
                "location": {
                    "accuracy": 1.0,
                    "location": {
                        "lat": 37.5669694,
                        "lng": -122.32645530000002
                    }
                },
                "source": "east"
            },
            {
                "bucket_id": "user123456:00166CF67F20:00166CF67F20.0",
                "labels": [
                    "California",
                    "San Mateo",
                    "Work",
                    "94401"
                ],
                "location": {
                    "accuracy": 1.0,
                    "location": {
                        "lat": 37.5669694,
                        "lng": -122.32645530000002
                    }
                },
                "source": "Office"
            },
            {
                "bucket_id": "user123456:00E04CC27CC8:00E04CC27CC8.0",
                "labels": [
                    "California",
                    "San Mateo",
                    "Work",
                    "94401"
                ],
                "location": {
                    "accuracy": 1.0,
                    "location": {
                        "lat": 37.5669694,
                        "lng": -122.32645530000002
                    }
                },
                "source": "west"
            }
        ]
    }
}

Search for cameras that match the argument text query. All query terms unrelated to camera names or camera labels are currently ignored. That is, the search is simply finding cameras that have a particular name or label associated with them.

URL Parameters

Name Description Details
text The query text that will be parsed to populate the Query object. Use the v: operator to search with a view_token (e.g. mexico v:vxy5q2). string, optional, example: work or home
num_results The number of results to return. int, optional, default: 10, max: 100

Content

Get Content (authenticated)

curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/me/cameras/Office/content/eyJ...OiJjYW1pbyJ9fQ

A specific content item (image or video) can be retrieved by its ID that is returned in the search response.

HTTP Request

GET https://camio.com/api/users/me/cameras/:camera/content/:id

URL Parameters

Name Description Details
camera The name of the camera. string, required, example: front
id The id of the content string, required

Get Content (with access_token)

The curl command is:

curl \
    -H "Content-Type: application/json" \
    -d '[{"id":"eyJsIjp7ImM...XMifX0", "access_token":"AQCahb56...TV0zm4TJ9pmrU4"}]' \
    -X POST https://camio.com/api/content/?resize=true&w=200&h=200

The JSON payload for the POST is a list of objects with only id and ‘access_token’:

[
  {
    "id":"eyJsIjp7ImM...XMifX0",
    "access_token":"AQCahb56...TV0zm4TJ9pmrU4"
  }
]

Get one or more content items (images or video) using a list of ids and access_tokens. POST is used so that the caller can supply a json list in the payload of the request.

HTTP Request

POST https://camio.com/api/content

URL Parameters

Name Description Details
w The width (in pixels) of the bounding box to resize the image to fit within. Only used if thumbnails are being fetched. int, optional, default: 150
h The height (in pixels) of the bounding box to resize the image to fit within. Only used if thumbnails are being fetched. int, optional, default: 112
quality The quality of the jpeg image compression. int, optional, min: 1, max: 100, default: 85
resize true to resize optional, true or false, default: false

JSON Payload

When requesting the content referenced in a search result of a Camio, you can supply a list of mappings between an id and access_token to authorized access to the content.

Name Description Details
id The id of the content string, required
access_token The access_token supplied in the result of a prior search that used view_tokens to authorize the search. string, required

Get Latest Live Image

The latest available live image can be retrieved from a specific camera.

HTTP Request

GET https://camio.com/api/content/live/:camera/

URL Parameters

Name Description Details
camera The name of the camera to fetch the lastest image from. string, required, example: front

Query Parameters

Name Description Details
user The email address of the owner of the camera. If the camera is owned by the current user this can be omitted. string, optional, example: test@example.com
quality The quality of the jpeg image compression. int, optional, min: 1, max: 100, default: 85
view_tokens The comma-separated list of view_tokens associated with Camio(s) that were shared without any end date (so that they extend to all FUTURE dates and are therefore permitted to server the latest live images. string, optional, example: 41cmi5mh66m8
output The output content type desired. string, optional, example: jpeg. When omitted, the default is json.
w The width (in pixels) of the bounding box to resize the image to fit within. int, optional, example 320. Default is full width.
h The height (in pixels) of the bounding box to resize the image to fit within. int, optional, example 180. Default is full height.

As an example of a public link that requires no OAuth Authorization header because of its use of the view_tokens query parameter, this is the latest live image from mailbox area of the Camio office, resized to a small thumbnail 320x180:

https://camio.com/api/content/live/east?view_tokens=41cmi5mh66m8&output=jpeg&w=320&h=180

To create a view_token for the latest live image of a single camera, see this help article. To create the view_token programatically with this API, create a Camio with a query object with only one camera in cameras, start_date without an end_date, and sort of asc.

Upload Content

The following cURL command uploads an MP4 via the Camio Box API:

curl -H "Content-Type:video/mp4" \
    -X POST \
    -T "filename.mp4" \
    "https://192.168.1.57/box/content/?camera_id=cam123&local_camera_id=local456&hash=abcdefghijk&timestamp=2017-04-22T13:44:12.0000"

Uploading video via Camio Box is the preferred method because of the bandwidth, precision, cost and quality benefits of analyzing video on your local network before sending anything to the cloud.

You POST video to the Camio Box /box/content endpoint with Query Parameters that associate the video with a registered camera. The video is segmented, analyzed, and labeled by the Camio pipeline. The indexed results are then accessible via the Search API or via the Camio webapp.

HTTP Request

POST https://192.168.1.57/box/content

URL Parameters

None. However you must obtain the ip_address of your Camio Box, which can be found on the camio.com/boxes page.

Query Parameters

TODO(carter) change accesstoken -> access_token

Name Description Details
accesstoken device_id of the Camio Box recieving the content string, required
local_camera_id the local_camera_id that was assigned to the camera by the user at the time of creating the camera string, required
camera_id the camera_id that was returned by camio.com at the time of creating the camera string, required
hash SHA sum of the content being posted, used to map segments back to the original source video string, required
timestamp the starting timestamp of the video in ISO8601 format YYYY-mm-ddTHH:MM:SS.FFFF string, required, example: 2014-07-21T20:38:32.183

Body

Upload Content (Cloud)

The following cURL command uploads an MP4:

curl -H "Content-Type:video/mp4" \
    -X POST \
    -T "filename.mp4" \
    "https://camio.com/api/users/abc123pdq/cameras/front/content/?camera_id=1234&upload_mode=video"

The following cURL command will upload a JPEG image:

curl -H "Content-Type:image/jpeg" \
    -X POST \
    -T "2014-07-21T20:38:32.183-07:00.jpeg" \
    "https://camio.com/api/users/51r6kndapc/cameras/front/content/2014-07-21T20:38:32.183-07:00.jpeg?camera_id=1234"

NOTE: The preferred method of uploading Content is via the Camio Box /box/content API. This cloud method of uploading is DEPRECATED.

Content can be uploaded to Camio via both POST and PUT. If the :name part of the url or filename part of a multi-part attachment specifies a parseable timestamp, then Camio will honor that timestamp if you include in options the value parse_timestamp.

HTTP Request

POST https://camio.com/api/users/me/cameras/:camera/content/:name

or

PUT https://camio.com/api/users/me/cameras/:camera/content/:name

URL Parameters

Name Description Details
camera The name of the camera. string, required, example: front
name An optional filename. If the filename includes a timestamp, it will be used to help synchronize sequences. string, optional, example: 2014-07-21T20:38:32.183-07:00.jpeg

Query Parameters

Name Description Details
camera_id The id of the camera. Any string that is unique among all the cameras belonging to the account is OK. It’s nice to use something reliably unique regardless of the owning account - such as the camera’s mac address - but you can create your own simpler id as well (e.g. cam123). string, required, example: 40523085002820672672296
upload_mode Indicates the type of content the camera uploads as the basis for Event creation. Set to video if the camera uploads only video as the basis for creating Events; otherwise, the uploaded video will be treated only as a secondary “backing” for Events created by image snapshots. string, optional, accepts: image, video, default: image
img_type The type of image (or video) being uploaded. Values include m for motion triggered, a for audio triggered, h for heartbeat uploads, and v for live snapshots. string, optional, default: m
rotation The degrees rotation required for the video to play in its correct orientation. string, optional, accepts: 0, 90, 180, 270, default: 0
video_length The length of the video in seconds as a floating point. Without supplying this value, the video length is calculated server-side with less precision string, optional, accepts numeric values > 0.0 like 20.18
options CSV string list of special processing options. Values include alternate when uploading alternate media of another resolution or encoding in support of an existing Event, no_analysis to accept uploaded video as-is as its own Event, without image analysis or machine learning, and parse_timestamp to infer timestamp of content from natural language processing of the uploaded filename. string, optional, accepts: alternate, no_analysis, parse_timestamp

Sample request is:

https://camio.com/api/users/me/cameras/Office/content/2016-01-19T00%3A59%3A09.119-0000.webm?camera_id=ccw0259026XYZ&video_length=6.452

The JSON response is:

{
    "camera": "Office",
    "camera_id": "ccw0259026XYZ",
    "content_type": "video/webm",
    "date_created": "2016-01-19T00:59:18.193-0000",
    "date_received": "2016-01-19T00:59:18.193-0000",
    "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw1NLtmwoM",
    "interest_hash": 0,
    "interest_score": 0.0,
    "ip_address": "73.170.185.225",
    "is_metadata_set": true,
    "labels": [],
    "name": "2016-01-19T00:59:09.119-0000.webm",
    "platform": "web",
    "size": 796042,
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
    "user_email": "test@example.com",
    "user_id": "11712X1",
    "video_length": 6.452
}

JSON Response

The JSON response echos the values supplied in the request and adds metadata derived from the request. The added metadata is described below.

Name Description Details
date_created The timestamp treated as the actual time of the Event in real life. If you’ve included &options=parse_timestamp in your request, then this value is determined by the parsing of the timestamp you supplied.
date_received The timestamp at which the content reached camio.com servers. This is the same as the date_created if you didn’t request &options=parse_timestamp.
id The unique id associated with this piece of content.
name The filename as derived from either the url or the filename in the multi-part attachment.
ip_address The IP address of the origin of the request.
size The size in bytes of the content uploaded.
user_agent The User-Agent from the request header.
user_email The email address of the owner of the account receiving the content.
user_id The unique id of the owner of the account receiving the content.

Jobs

A Job tracks the completion of a long-running batch import operation.

Each Job has one or more Shards, and each Shard receives a JSON payload from the client that describes the SHA hash of the video file and its correlation to the original filename. That way, a mapper can subsequently check the completion status of the asynchronous labeling of all the video events associated with the input video file.

List all Jobs

An example request is:

curl \
    -H "Authorization: token oauth123xyz" \
    https://camio.com//api/jobs

The JSON response is:

[
    {
        "job_id": "agpIDYggsM",
        "request": {
            "device_id": "d123pdq",
            "item_count": 4099, 
            "item_average_size_bytes": 512, 
            "cameras":[
                {"name": "starboard"}
            ],
            "earliest_date":"2017-04-30T05:17:22.551-0700", 
            "latest_date": "2017-05-17T16:35:36.362-0700"
        },
        "shard_map": {
            "0": {
                "item_count": 2048,
                "job_id": "agpIDYggsM",
                "shard_id": "0",
                "status": "missing"
            },
            "1": {
                "item_count": 2048,
                "job_id": "agpIDYggsM",
                "shard_id": "1",
                "status": "missing"
            },
            "2": {
                "item_count": 3,
                "job_id": "agpIDYggsM",
                "shard_id": "2",
                "status": "missing"
            }
        },
        "status": "shards_missing"
    }
]

This lists all Jobs that were created by the current user. This command fetches the status of each Job with each call.

Job Status

The Job status values are:

Value Description
shards_missing One or more of the Job’s shards haven’t yet been uploaded via the PUT :upload_url.
running All shards have been uploaded and the Job is running.
completed All shards of the Job have been labeled, so the Job is complete.

Job Shard Status

The Job Shard status values are:

Value Description
missing The Shard hasn’t been uploaded via the PUT :upload_url.
running The Shard has been uploaded and is being labeled.
completed The Shard has been labeled.

HTTP Request

GET https://camio.com/api/jobs

Get Specific Job

An example request is:

curl \
    -H "Authorization: token oauth123xyz" \
    https://camio.com//api/jobs/agpIDYggsM

The JSON response is:

{
    "job_id": "agpIDYggsM",
    "request": {
        "device_id": "d123pdq",
        "item_count": 4099, 
        "item_average_size_bytes": 512, 
        "cameras":[
            {"name": "starboard"}
        ],
        "earliest_date":"2017-04-30T05:17:22.551-0700", 
        "latest_date": "2017-05-17T16:35:36.362-0700"
    },    
    "shard_map": {
        "0": {
            "item_count": 2048,
            "job_id": "agpIDYggsM",
            "shard_id": "0",
            "status": "missing"
        },
        "1": {
            "item_count": 2048,
            "job_id": "agpIDYggsM",
            "shard_id": "1",
            "status": "missing"
        },
        "2": {
            "item_count": 3,
            "job_id": "agpIDYggsM",
            "shard_id": "2",
            "status": "missing"
        }
    },
    "status": "shards_missing"
}

HTTP Request

GET https://camio.com/api/jobs/:job_id

URL Parameters

Name Description Details
job_id The job_id returned from the PUT /api/jobs string, required.

See Job Status and Job Shard Status for the status values.

Create Job

An example request is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{item_count": 4099, "item_average_size_bytes": 512, cameras":[{"name": "starboard"}], "earliest_date":"2017-04-30T05:17:22.551-0700", "latest_date": "2017-05-17T16:35:36.362-0700", "device_id": "d123pdq"}' \
    -X POST https://camio.com/api/jobs

The JSON response is:

{
    "job_id": "agpIDYggsM",
    "request": {
        "device_id": "d123pdq",
        "item_count": 4099, 
        "item_average_size_bytes": 512, 
        "cameras":[
            {"name": "starboard"}
        ],
        "earliest_date": "2017-04-30T05:17:22.551-0700", 
        "latest_date": "2017-05-17T16:35:36.362-0700"
    },    
    "shard_map": {
        "0": {
            "item_count": 2048,
            "job_id": "agpIDYggsM",
            "shard_id": "0",
            "upload_url": "https://storage.googleapis.com/camio_test_mr_output/bij-agpIDYggsM-0?GoogleAccessId=397790679937@developer.gserviceaccount.com&Expires=1493001520&Signature=Jl4q%2FhXGTpNNRPWw6nQYnT0YxR%2BYHap38s1GmF0crKJIyW5p0YOb1BfECeG5mTd4HCWI0hi7I4ZVe2xwdOSgajvdOJPFEEm%2Fig%2F8xgwm6JQv8lq3CGVXJsJtKj9UervBnCJrr2dxE788RElTXCSljh5DfFBXDhDH09%2BQx8B5sWc%3D"
        },
        "1": {
            "item_count": 2048,
            "job_id": "agpIDYggsM",
            "shard_id": "1",
            "upload_url": "https://storage.googleapis.com/camio_test_mr_output/bij-agpIDYggsM-1?GoogleAccessId=397790679937@developer.gserviceaccount.com&Expires=1493001520&Signature=kXfCRwkDudTAiFCW%2BvXgTR%2Bv0r3QtBiIBI%2Bc%2FjhjspGen2ZbBem04NJ3rmMueCNddfeUvOkyC3sVkJ4J%2FGsdcrCyp8WxWmI9lclh0YWPHKUkFAfSIyGVdSuUBZbieLzcZXjROVeR2aWknM6NQUEyZKL15HcRzTjA8QWEUppI6tM%3D"
        },
        "2": {
            "item_count": 3,
            "job_id": "agpIDYggsM",
            "shard_id": "2",
            "upload_url": "https://storage.googleapis.com/camio_test_mr_output/bij-agpIDYggsM-2?GoogleAccessId=397790679937@developer.gserviceaccount.com&Expires=1493001520&Signature=L80gTRdfzFqEd7znyJ3qHQlTVRJaIWjXcA6G2RujCmDpALPW3CVoIfoVzOX2jwmq0Q%2BGM6IrMA664%2BH0%2FBRDNgE1NPtwT763cLutiwGAwUwnrLyP3WxF4Ysmdb5Da2syiiufe7amT4%2FpSbWAyn2b59cqNmK%2Fh0FUlAi7cW88gek%3D"
        }
    }
}

The command on the right creates a new Job with 4099 items, where each item is about 512 bytes in size. The server determines how many shards are required and responds with a shard_map keyed by shard_id with values that describe the item_count of each shard and the upload_url that will receive the payload describing that particular shard.

HTTP Request

PUT https://camio.com/api/jobs

Body

The JSON body is the job request described by these fields.

Name Description Details
item_count The total count of all items in the Job. integer, required.
item_average_size_bytes The average size of each individual item in bytes. This is the size of only the filename + hash + any other metadata (NOT the size of the video itself) integer, required.
device_id Only if you want it for accounting, include the device_id of the Camio Box processing the job String, optional.
cameras The list of camera objects included in the job, and only the name field of the camera is required List of cameras, only camera.name required.
earliest_date The earliest date in the video submitted for this job ISO8601 String, required. e.g. "2017-04-30T05:17:22.551-0700"
latest_date The latest date in the video submitted for this job ISO8601 String, required. e.g. "2017-05-17T16:35:36.362-0700"

Create Job Shard Hash Map

When you create a Job, the JSON response includes the signed upload_url to use for the PUT of the hash_map for each Shard of the Job. NOTE: the upload_url returned in the response is signed and valid only for a limited duration of time (e.g. 20 minutes), so it’s important that you upload all Shards of your Job immediately after creating the Job.

The key of the hash_map is the SHA hash of the input video file like this:

{
  "job_id": "agpIDYggsM",
  "shard_id": "0",
  "item_count": 2048,
  "hash_map":{
    "xyzpdq123": {"original_filename": "HiC2_20170324T120123000"},
    "xyzpdqABC": {"original_filename": "HiC2_20170324T120133000"}
  }
}

HTTP Request

PUT :upload_url

URL Parameters

Name Description Details
upload_url The upload_url of the shard that was returned from PUT /api/jobs. The signed url expires, so you must perform this PUT within 20 minutes of creating the Job. string, required.

An example Hook upon job_completed

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"callback_url": "https://mycompany.com/job-completed", "type": "job_completed"}' \
    -X POST https://camio.com/api/users/me/hooks

The payload delivered to the callback_url for job_completed is:

{
  "job_id": "job123",
  "type": "job_completed",
}

To be notified upon completion of the job, create a Hook with the type job_completed as shown in the example on the right.

Your callback_url (https://mycompany.com/job-completed) for the Hook performs whatever post-labeling actions are required for your application (e.g. using /api/search to fetch the events with particlar labels).

Delete Job

An example request is:

curl \
    -H "Authorization: token xyzauthtoken" \
    -X DELETE \
    https://camio.com/api/jobs/agpIDYggsM

The response is:

204 (No Content)

Deleting a Job doesn’t stop the labeling that was already underway. So deleting a Job is really only usefule if you prefer to purge the history of Jobs indexed under your user_id.

HTTP Request

DELETE https://camio.com/api/jobs/:job_id

URL Parameters

Name Description Details
job_id The id of the Job. string, required.

Camios

A Camio is a portion of your content that can be shared by link without requiring viewers to sign-in. You define the subset of your content to share, then send a link that enables others to view the Camio without sign-in.

List all Camios

An example request is:

curl "https://camio.com/api/users/me/camios" \
    -H "Authorization: token abc123"

The JSON response is:

[
    {
        "date_created": "2017-04-10T04:20:47.118-0000",
        "name": "Query link Liverpool 6:45pm EDT April 9 2017 to 11pm EDT April 9 2017 all",
        "owner": {
            "user_id": "user123456"
        },
        "query": {
            "cameras": [
                "Liverpool"
            ],
            "content_type": "image",
            "date": "2017-04-09T22:45:00.000-0000",
            "earliest_date_allowed": "2017-04-09T22:45:00.000-0000",
            "labels": [],
            "latest_date_allowed": "2017-04-10T03:00:00.000-0000",
            "user": "jcmaslan@gmail.com"
        },
        "type": "public",
        "view_token": "AQCCckxhtQEzx_G5rU_4iRym7awAqth9jQrKDSnAGBe0CJbpUi1tvXkiZs5gTaPF0Tt9fD_p27_9nPotu6oSBobt"
    },
    ...
]

HTTP Request

GET https://camio.com/api/users/me/camios

Create Camio

An example request is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token abc123" \
    -X POST \
    -d '{"name": "Query link Liverpool 6:45pm to 11pm","query": {"text": "Liverpool 6:45pm EDT April 9 2017 to 11pm EDT April 9 2017 all jcmaslan@gmail.com"},"type": "public"}' \
    https://camio.com/api/users/me/camios

An example of the body of the JSON request is:

{
    "name": "Query link Liverpool 6:45pm to 11pm",
    "query": {
        "text": "Liverpool 6:45pm EDT April 9 2017 to 11pm EDT April 9 2017 all jcmaslan@gmail.com"
    },
    "type": "public"
}

The JSON respons is:

{
    "date_created": "2017-04-10T04:20:47.118-0000",
    "message": {
        "body": "See this #Camio https://camio.com/c/s1ui6ygpwveo/app via @camio",
        "subject": "See this Camio Query Link",
        "url": "https://camio.com/c/s1ui6ygpwveo/app"
    },
    "name": "Query Link Liverpool 6:45pm to 11pm",
    "owner": {
        "user_id": "user123456"
    },
    "query": {
        "cameras": [
            "Liverpool"
        ],
        "date": "2017-04-09T22:45:00.000-0000",
        "earliest_date_allowed": "2017-04-09T22:45:00.000-0000",
        "labels": [],
        "latest_date_allowed": "2017-04-10T03:00:00.000-0000",
        "motion_type": "all",
        "sort": "asc",
        "user": "jcmaslan@gmail.com",
    },
    "type": "public",
    "url": "https://camio.com/c/s1ui6ygpwveo/app",
    "view_token": "AQCCckxhtQEzx_G5rU_4iRym7awAqth9jQrKDSnAGBe0CJbpUi1tvXkiZs5gTaPF0Tt9fD_p27_9nPotu6oSBobt",
    "view_token_short": "s1ui6ygpwveo"
}

When enumerating Events instead, the input JSON is:

{
    "name": "My Camio",
    "query": {
        "events": ["IDXYZ", "IDABC", "IDDEF"]
    },
    "type":"public"
}

Specify the details of the camio as JSON in the POST body. The query input may specify either query.text or query.events. Learn more about Camio Query Links, but the most common sharing is via the enumerated event ids specified as a list in query.events.

HTTP Request

POST https://camio.com/api/users/me/camios

Body

Name Type Description
name string Optional. Defaults to the query description.
query Query Query that defines the constraints on the Camio.
type string Optional. “public” or “private” - default is “public”.

Create Camio Download

Create a Download that includes all content of the Camio. This API endpoint references Camios that have already been created by a user with the /users/me/camios endpoint.

The JSON response is:

[
    {
        "To Be Determined":"soon"
    }
]

The POST must include an OAuth token identifying the requesting user, since that user will receive an email notification once the download is ready.

Currently, downloads can only be created (no listing, GET, or DELETE) and the :view_token parameter can be supplied only in the URL itself (any JSON in the POST body is ignored).

HTTP Request

POST https://camio.com/api/camios/:view_token/downloads

URL Parameters

Name Description Details
view_token The Camio view_token. string, required, example: AxqTV1abzQ

Delete Camio

An example request is:

curl \
    -H "Authorization: token abc123" \
    -X DELETE \
    https://camio.com/api/users/me/camios?view_token=vtok123

The response is:

204 (No Content)

HTTP Request

DELETE /api/users/me/camios

URL Parameters

Name Description Details
view_token The token view_token returned by the creation of the Camio. string, required.

Upload Token

An Upload Token is an encrypted string that permits only the uploading of content. It provides no access to content.

Get Upload Token

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/users/me/tokens/upload

The JSON response is:

"AQBrSFvOPxQj2prnCh2wvocHnAbu_5szaBeFdQsktgE4Vw"

This retrieves the Upload Token only for the currently authenticated user.

HTTP Request

GET https://camio.com/api/users/me/tokens/upload

Get Upload Token Hint

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/tokens/AQBrSFvOPxQj2prnCh2wvocHnAbu_5szaBeFdQsktgE4Vw/hint

The JSON response is:

{"email":"test@..."}

Sometimes camera installers need to validate that a particular Upload Token corresponds to the user that owns the cameras being installed. So this GET or POST request returns a hint to display a portion of the email address of the user that owns the upload_token. The request requires authentication, but the requester doesn’t have to be the owner of the upload_token.

HTTP Request

GET https://camio.com/api/tokens/:upload_token/hint

or

POST https://camio.com/api/tokens/:upload_token/hint

URL Parameters

Name Description Details
upload_token The Upload Token you’d like to validate with a response containing a hint displaying the user that owns the Upload Token. string, required, example: AQBrSFvOPxQj2prnCh2wvocHnAbu_5szaBeFdQsktgE4Vw

Readings

The /api/search response includes sensor_data:

{
    "query": {...},
    "result": {
        "bucket_type": "event",
        "buckets": [
            {
                "bucket_id": "ag1zfmNhbWlvbG9nZoyOTowMi45NjYwMDAM",
                "sensor_data": [
                    {
                        "accelerometer_x": -0.2587,
                        "accelerometer_y": 6.1552,
                        "accelerometer_z": 7.6353,
                        "location_accuracy": 19.35484,
                        "location_lat": 37.58162,
                        "location_lng": -122.36906,
                        "sound_level": 67.353,
                        "timestamp": "2016-01-01T16:49:54.061-0800"
                    }
                ],
                "labels": [
                    "door opened",
                    "_ml_human"
                ],
                ...
            },
            ...
        ]
    }
}

Readings enable arbitrary sensor data to be correlated with video events returned in Search results. The timestamp of the Reading is used to correlate the Reading with the video events that span that timestamp.

The Search results include sensor_data whenever any of the search result buckets have Readings associated with them.

Camio accepts multiple data formats for these Readings. The examples are illustrated with the data format used by the AndroSensor app. Please contact us to request support for a particular data format.

Create Readings

Example requests with only location data:

curl \
    -H "Content-Type: application/json" \
    -d '[{"timestamp": "2017-05-03T17:04:51.460+0800", "location_lat": 30.54316833333333, "location_lng": 104.07076333333335, "location_accuracy": 4.300000190734863}]' \
    -X PUT https://camio.com/api/users/xyzpdq123/devices/BOAT1/readings

and with 4G/LTE camera format:

curl \
    -H "Content-Type: application/json" \
    -d '{"sensordata": [{"utc_time"": "2017-05-03T17:04:51.460+0800", "location": {"latitude": 30.54316833333333, "longitude": 104.07076333333335, "accuracy": 4.300000190734863}}]}' \
    -X PUT https://camio.com/api/users/xyzpdq123/devices/BOAT1/readings

The JSON response is:

["r1"]

The command on the right associates a single latitude and longitude with any video event that spans the timestamp 2017-05-03T17:04:51.460+0800.

HTTP Request

POST https://camio.com/api/users/:upload_token/devices/:device_id/readings

URL Parameters

Name Description Details
upload_token the Upload Token of the account or the value me if using OAuth Authorization header instead. string, optional, example: xyzpdq123.
device_id any String that uniquely identifies the device within your account. string, required, example: BOAT1.

Query Parameters

Name Description Details
camera_name the name of the camera to which these readings apply if they don’t apply to all of the user’s cameras. string, optional, example: starboard.

Annotations

Annotations enable arbitrary labels to be addeded to video events. For example, you may want to annotate video events with access control labels like “door opened” or with sensor interpretations like “collision”.

Annotations must include a timestamp so that they can be correlated with the video events that span that timestamp.

Unlike Readings, which can be created prior to the creation of their corresponding video events, Annotations must arrive after your video events have been created. i.e. your PUT /api/users/:upload_token/devices/:device_id/annotations must happen after the Camio servers have received your video content.

Create Annotations

An example request is:

curl \
    -H "Content-Type: application/json" \
    -d '[{"timestamp":"2017-05-03T17:04:51.460+0800","labels_to_add":["unlocked"],"labels_to_remove":[]}]' \
    -X PUT https://camio.com/api/users/xyzpdq123/devices/BOAT1/annotations

The JSON response is:

{
    "ag1zfmNhbc29uDA": {
        "labels_to_add": [
            "unlocked"
        ],
        "labels_to_remove": []
    },
    "agDNkMy5qc29uDA": {
        "labels_to_add": [
            "unlocked"
        ],
        "labels_to_remove": []
    }
}

The command on the right associates the label door opened with any video event that spans the timestamp 2017-05-03T17:04:51.460+0800.

HTTP Request

POST https://camio.com/api/users/:upload_token/devices/:device_id/annotations

URL Parameters

Name Description Details
upload_token the Upload Token of the account or the value me if using OAuth Authorization header instead. string, optional, example: xyzpdq123.
device_id any String that uniquely identifies the device within your account. string, required, example: BOAT1.

Response

The JSON response is a dictionary keyed by event_id to be annotated with the list of labels_to_add and labels_to_remove.

Interactions

This API endpoint is used only by Camio’s own client apps or by partner apps that display video events in customized video viewers. It’s a POST-only endpoint that records user interactions with Events as input to Camio’s Machine Learning that ranks the importance of Events.

Create an Interaction

An example of the body of the JSON request is:

{
    "actions": [
        {
            "action_date": "2016-01-18T15:46:56.049-0800",
            "action_type": "skim",
            "camera": "outdoor",
            "common_context": [
                "Ni0wMS0xNlQxNzoyOToxNy4yOTIwMDAM",
                "Ni0wMS0xNlQxNzoyNzo0OC40ODQwMDAM",
                "Ni0wMS0xNlQxNzowODozMy4xNTgwMDAM",
                "Ni0wMS0xNlQxNjo1Mzo1NS40MTkwMDAM",
                "Ni0wMS0xNlQxNjozOTozMy45NjkwMDAM",
                "Ni0wMS0xNlQxNjoyNjoyMS4xNTAwMDAM",
                "Ni0wMS0xNlQwMDowODo0MS41MTYwMDAM",
                "Ni0wMS0xNVQyMjowMTo1OC40NzIwMDAM",
                "Ni0wMS0xNlQxOTo1MDoxOS43NzEwMDAM",
                "Ni0wMS0xNlQxODo0MTo0NC4yOTYwMDAM",
                "Ni0wMS0xNlQxODo0MToxMi4wOTEwMDAM",
                "Ni0wMS0xOFQwMDo1MToyOC45NDMwMDAM",
                "Ni0wMS0xOFQwMDo1NDo1Ni42MTQwMDAM",
                "Ni0wMS0xOFQwMDo1Njo0Ni40MDUwMDAM",
                "Ni0wMS0xOFQwMTowNzozMy44MDMwMDAM",
                "Ni0wMS0xOFQwNDozNDo0OC43MDUwMDAM",
                "Ni0wMS0xOFQwNjo0MjoxNi4xNDIwMDAM",
                "Ni0wMS0xOFQxMzoyMzoyOS4yNjkwMDAM",
                "Ni0wMS0xOFQxNToxNjoyNC4wNTQwMDAM",
                "Ni0wMS0xOFQxNTo0NjozMi45ODkwMDAM"
            ],
            "event_id": "Ni0wMS0xN1QyMjowMDo1Mi41MzgwMDAM",
            "particular_context": [],
            "skim_direction_changes": 4,
            "total_frames_in_event": 15,
            "total_frames_viewed": 22,
            "unique_frames_viewed": 12
        }
    ],
    "device_type": "pc",
    "first_event_date": "2016-01-17T22:00:52.538-0000",
    "hash": "#search;q=people+approaching+outdoor+walkway+7am+yesterday+in+shades"
}

The response is:

204 (No Content)

Specify the details of the interaction as JSON in the POST body.

HTTP Request

POST https://camio.com/api/users/me/interactions

Body

Name Type Description
first_event_date string The earliest date of any event included in the interaction.
device_type string The type of device on which the action was performed ( “pc”, “tablet”, “phone” ).
actions List of objects List of Action objects.
hash string optional, for browser-based viewers that maintain state in the url hash.

Action object

Name Type Description
event_id string “e123”
action_type string required, up, down, share, hide, unhide, enlarge, play, skim, star.
action_date string Date on which the user interaction occurred. e.g. “2016-01-18T15:46:56.049-0800”
events_in_view List of strings The event ids that were in view at the time of the user interaction.
total_frames_in_event integer The total number of frames in the event itself; even though the server knows this number, supplying this value is appreciated to reduce server processing costs.
total_frames_viewed integer The total number of frames actually viewed by the user.
unique_frames_viewed integer The actual number of unique frames that were viewed by the user prior to the action.
device_type string The type of device on which the action was performed ( “pc”, “tablet”, “phone” ).
skim_direction_changes integer When the user scrubs back-and-forth while previewing the frames of event, this is the number of times that the user changed direction.
common_context List TBD
particular_context List TBD

Settings

This endpoint gets and sets the user’s notification preferences and recording state. It also includes the user’s Upload Token in the GET response even though the Upload Token cannot be modified directly with a POST (the Upload Token changes only in response to the user changing his/her Upload Code which is not yet supported in the API).

Get Settings

Fetch the user’s current settings.

The JSON response is:


 {
    "notifications": {
        "motion_alerts" : {
            "state" : "ON",
            "method" : "PUSH",
            "options" : "mute street,window"
        },
        "camera_diagnostics" : {
            "state" : "ON",
            "method" : "EMAIL",
            "options" : ""
        },
        "announcements" : {
            "state" : "ON",
            "method" : "EMAIL",
            "options" : ""
        },
        "newsletters" : {
            "state" : "ON",
            "method" : "EMAIL",
            "options" : ""
        },
        "camio_daily" : {
            "state" : "ON",
            "method" : "EMAIL",
            "options" : ""
        }
    },
    "upload_token" : "ABQR123",
    "recording_enabled" : true
}

HTTP Request

GET https://camio.com/api/users/me/settings

Body

Notification Attributes

Name Description Details
notifications The dictionary of notification preferences by type of notification. Dictionary.
recording_enabled false to override the settings of all cameras to stop saving uploads on the server. boolean.
upload_token The read-only Upload Token for the user’s account. string.

Notifications Types

Name Description Details
motion_alerts Sent when interesting motion is detected in specific zones and cameras. NotificationPreference object.
camera_diagnostics Sent when a problem with a particular camera is detected. NotificationPreference object.
announcements Info on new features, enhancements and changes. NotificationPreference object.
newsletters Tips, news, and information related to uses of Camio. NotificationPreference object.
camio_daily Daily summary of interesting events. NotificationPreference object.

Get Settings (Local Camio Box)

An example request is:

curl http:192.168.1.57:8080/box/settings

The JSON response is:

{
  "device_id": "ZADfg23_98kuS-3FyLv2oxbPrsOP56wlUUde8X2B_7B2hBv3-t56bk-sRoBVgaonxCMpi4CAmLkvmT0fz",
  "user-agent": "Linux (x86/64) Camio Box VirtualBox 2017-04-22:ab234badsfb293nas9db9f7231arereds",
}

Fetch the settings from a locally running Camio Box on your network that is operating as an API endpoint for batch imports.

This endpoint serves as a simple way to get some necessary information about the Camio Box you are using for segmentation. To POST content to Box, you’ll need to supply the device_id as a form of a shared secret and you’ll need to supply the same value when registering a camera for batch imports.

HTTP Request

GET http://192.168.1.57/box/settings

Update Settings

The POST must include an OAuth token for the signed-in user in the HTTP Authorization Header.

HTTP Request

POST https://camio.com/api/users/me/settings

Body

Name Description Details
notifications The dictionary of notification preferences by type of notification. See the NotificationPreference values in the table below. Dictionary of NotificationPreference objects.
recording_enabled true or false to enable or disable recording of uploaded content. If false, then this value overrides the settings for each individual camera.
upload_token This is a read-only value that cannot be changed by the caller. When present in a POST/PUT/PATCH, this value is ignored.

NotificationPreference attributes

Name Description Details
state The “ON” or “OFF” state of the notification type. string, required. “ON” or “OFF”.
method The method of delivery for the particular notification type. string, required. “EMAIL” or “PUSH”.
options Applicable to motion_alerts only to specify any muted camera or label names. e.g. “mute driveway,street” to suppress alerts from the driveway and street zones. The empty string means all alerts are sent.

Requests

These API endpoints create requests for Camio Box to process asynchronously.

Create a Configuration Request

The cameras referenced in the requests must be connected to a Camio Box.

An example request is:

curl \
    -H "Content-Type: application/json" \
    -d '{"A1A2A3A4A5AA.0":{"local_camera_id": "A1A2A3A4A5AA.0","mac_address": "A1A2A3A4A5AA", "device_id": "BAQF123abc"}}' \
    -X PUT https://camio.com/api/cameras/requests/configuration

The JSON payload is keyed by local_camera_id:

{
    "A1A2A3A4A5AA.0": {
        "local_camera_id": "A1A2A3A4A5AA.0",
        "mac_address": "A1A2A3A4A5AA",
        "device_id": "BAQF123abc"
    }
}

The response is:

204 (No Content)

This automatically applies all camera configuration settings defined by this repo. Only the owner of the account or a Guest with “Can Manage” permission can make this request.

HTTP Request

PUT https://camio.com/api/cameras/requests/configuration (all except WiFi)

PUT https://camio.com/api/cameras/requests/configuration/wifi (WiFi only)

Body

Each entry in the JSON dictionary must specify the local_camera_id, mac_address and device_id.

Create a Thumbnail Request

This requests that a new thumbnail be fetched from the specified camera(s).

An example request is:

curl \
    -H "Content-Type: application/json" \
    -d '{"A1A2A3A4A5AA.0":{"local_camera_id": "A1A2A3A4A5AA.0","mac_address": "A1A2A3A4A5AA", "device_id": "BAQF123abc"}}' \
    -X PUT https://camio.com/api/cameras/requests/thumbnails

The JSON payload is keyed by local_camera_id:

{
    "A1A2A3A4A5AA.0": {
        "local_camera_id": "A1A2A3A4A5AA.0",
        "mac_address": "A1A2A3A4A5AA",
        "device_id": "BAQF123abc"
    }
}

The response is:

204 (No Content)

HTTP Request

PUT https://camio.com/api/cameras/requests/thumbnails

Body

Each entry in the JSON dictionary must specify the local_camera_id, mac_address and device_id.

Profile

The user’s profile is used only to interpret times and dates in the text parameter of the Search API that omit a timezone specification.

For example, the query text “7am to 8am” performed by a user whose profile has timezone_offset of -0700 will search from 2pm GMT to 3pm GMT. That is, this API call:

https://camio.com/api/search/?text=7am+to+8am

results in this date interpretation:

"earliest_date_allowed":"2017-07-21T14:00:00.000-0000", "latest_date_allowed":"2017-07-21T15:00:00.000-0000"

Create a Profile

An example command:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \    
    -d '{"timezone_offset": "-0700"}' \
    -X PUT https://camio.com/api/users/me/profile

An example response:

{
    "email": "test@example.com",
    "timezone": {
        "timezone_offset": "-0700"
    },
    "user_id": "user123"
}

The input payload may specify either timezone_offset or timezone_offset_minutes (if both were specified accidentally, then the timezone_offset value trumps the other value).

Name Description Details
timezone_offset a 5-character string with the offset from GMT. string, optional. e.g. "-0700".
timezone_offset_minutes The integer returned from javascript’s getTimezoneOffset(). integer, optional. e.g. 420.

Get a Profile

An example command:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/me/profile

An example response:

{
    "email": "test@example.com",
    "timezone": {
        "timezone_offset": "-0700"
    },
    "user_id": "user123"
}

Get an existing user profile.

Data

The /api/data/counters/events endpoint serves a Data Source that supports the Google Visualization API Query Language so that it’s easier to import data into spreadsheets and applications.

The default output format is out:json. You can request a different output format by using the tqx URL Parameter with the key/value pairs out:csv, out:html and out:tsv-excel.

For example, get HTML output from a query like this: https://camio.com/api/data/counters/events?tq=select%20camera_name,sum(count)%20group%20by%20camera_name&tqx=out:html

And get CSV output from that same query with the URL Paramter &tqx=out:csv like this: https://camio.com/api/data/counters/events?tq=select%20camera_name,sum(count)%20group%20by%20camera_name&tqx=out:csv

Event Counters

An example request:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/data/counters/events?tq=select%20camera_name,sum(count)%20group%20by%20camera_name

The response is javascript for the Google Visualization API:

google.visualization.Query.setResponse({"version":"0.6","status":"ok","sig":"1344270664","table":{"cols":[{"id":"camera_name","label":"Camera Name","type":"string","pattern":""},{"id":"sum-count","label":"sum Count","type":"number","pattern":""}],"rows":[{"c":[{"v":"Chrome"},{"v":1.0}]}]}});

GET https://camio.com/api/data/counters/events

URL Parameters

Name Description Details
tq A query written in Google Visualization API query language, specifying how to filter, sort, or otherwise manipulate the returned data. The string does not need to be quoted. string, optional.
tqx A set of colon-delimited key/value pairs for standard or custom parameters. Pairs are separated by semicolons. out:json is the default; out:csv, out:html and out:tsv-excel are also supported. string, optional, example &tqx=out:csv
user The email address of the user that owns the account string, optional, example test@example.com
period The number of days of historical data to retrieve, expressed in units like 3d for 3 days. string, optional, default 7d

Data Source Fields

The Data Source for hourly Event counters includes the following fields.

Name Description Details
camera_name The name of the camera of the counter. TEXT
count The total number of Events analyzed in the hour of the counter. NUMBER
counter_date The DATETIME of the beginning of the hour of the counter. DATETIME
user_id The user_id of the owner of the account. TEXT
hour The numeric hour 0-23 of the counter. NUMBER
counter_date_formatted The counter_date formatted as a string like “2017-08-27” (“yyyy-MM-dd”) TEXT

Spreadsheets

To see the data in an always-up-to-date Google Spreadsheet, you can use the ImportData function with your Camio Upload Token for Authorization. For example, if you’ve pasted your Upload Token into cell A1, then your formual might look like this:

=ImportData(CONCATENATE("https://camio.com/api/data/counters/events/?token=",$A$1,"&period=7d&tq=select%20camera_name,sum(count) group by camera_name&tqx=out:csv"))

There’s an example spreadsheet at: http://go.camio.com/data-api-example

Errors

The Camio API uses standard HTTP status codes.