Recordings API

The Recordings API allows users to archive live imagery from cameras in the Helios network. The primary endpoints are the Index, Create, and Download methods, which allow users to search for existing recordings, create their own new recording, and download the archived camera data.

Recordings are intended to be short-lived resources and will be accessible for 90 days from the time the recording was created. After that time period has expired, the recording and all associated imagery may be removed from the system.

Index

Return a list of recordings matching the provided spatial, text, or metadata filters

Request

GET  https://api.helios.earth/v1/recordings  or
POST https://api.helios.earth/v1/recordings/_search

Query Parameters

When submitting a search using a GET request, all query parameters are specified as part of the query string. For POST requests, query parameters can either be submitted using a content type of application/json or x-www-form-urlencoded. See API Basics for more information.


q Query string that searches across multiple text fields
bbox GeoJSON format bounding box e.g. -180,-90,180,90
polygon Comma separated coordinate pairs. Each coordinate pair consists of the longitude and latitude, separated by a space. It is recommended that the first and last coordinate pairs be equal to properly close the polygon.

e.g. -105 40,-100 36,-110 38,-105 40
lat, lon, radius Geospatial point radius query. lat and lon are specified in degrees. Radius is optional and can be specified in either meters (no units), kilometers, or miles e.g. 10000 or 10km or 10mi. If no radius is specified, a default value of 10km is assumed.
polyline, polyline_precision, polyline_radius Geospatial polygon search using the encoded polyline format used by routing providers. The polyline_precision defaults to a precision of 5, which is used by Google Maps. For OSRM-based routing providers like Mapbox Directions, use a precision value of 6. The polyline_radius provides a buffer around the supplied polyline and is specified in kilometers, with a default value of 1.

Note: Polylines can be quite large for complex routes and there is a limit on the size of a query string for GET requests, so it is recommended that you use POST requests to submit searches that include this parameter.
country Country where the camera is located e.g. United States, Canada
state State where the camera is located e.g. California, New York
city City name where the camera is located. While the region is a generalized location, the city represents the actual physical location of the camera. e.g. city=Long Beach, region=Los Angeles
camera_id Show recordings for only this camera ID
status complete, submitted, failed
duration_min, duration_max Recording duration in seconds
start_min, start_max Recording start time, specified in UTC as an ISO 8601 string (e.g. 2013-07-01 or 2013-07-01T12:34:56.000Z)
stop_min, stop_max Recording stop time, specified in UTC as an ISO 8601 string (e.g. 2013-07-01 or 2013-07-01T12:34:56.000Z)
limit Limit value for pagination. Defaults to 10. Max value of 100 is allowed.
skip Skip value for pagination. Defaults to 0. Max value of 4000 is allowed.
sort Sort parameter: country, state, city status, duration, start, stop, distance are currently allowed
sort_dir Sort direction: asc or desc (default is asc)
aggs

Aggregate and summarize the results set based on the following attributes: country, state, city, tags, status, duration, camera_id.


Multiple aggregations can be requested using array syntax or by listing them comma-delimited, e.g: 

aggs[]=state&aggs[]=city
aggs=state,city

For each requested aggregation, up to ten values and their respective recording counts will be returned. For instance, if the state aggregation is requested, the results will include the ten states with the highest number of recordings matching the specified search query parameters, along with the total count for each of those states.

Response

GeoJSON Feature Collection

HTTP 200

{
  "type": "FeatureCollection",
  "bbox": [...],
  "features": [
    {
      "type": "Feature",
      "id": "6f228350-d7ad-4e8a-afb0-27ea3348cbe1",
      "geometry": {
        "coordinates": [-95.216163,29.61579],
        "type":"Point"
      },
      "properties": {
        "camera_id": "TL-7652",
        "country": "United States",
        "state": "Texas",
        "region": "Houston, TX",
        "city": "Houston",
        "description": "I-45 Gulf @ Fuqua St",
        "status": "complete",
        "duration": 1800,
        "rate": 10,
        "start": "2017-08-27T13:35:14.000Z",
        "stop": "2017-08-27T14:05:14.000Z",
        "tags": [],
        "created_at": "2017-08-27T13:35:14.068Z",
        "formats": ["jpg", "mp4", "zip"]
      }
    }
  ],
  "properties": {
    "limit": 1,
    "skip": 0,
    "total": 10,
    "aggs": {
      "state": [
        {"key": "Texas":, "doc_count": 10}
      ]
    }
  }
}

Show

Return the attributes for a single recording

Request

GET https://api.helios.earth/v1/recordings/:id

Response

HTTP 200, GeoJSON Feature

Create

Create a new camera recording

Request

POST https://api.helios.earth/v1/recordings

Body Params

camera_id ID of the camera to be recorded
duration Recording duration in seconds. Default is 300 seconds (5 minutes) if not specified. Max value is 1800 seconds (30 minutes).
start (optional) Recording start time, specified in UTC as an ISO 8601 string (e.g. 2017-07-01T12:34:56.000Z). If a value is not specified, the recording start time will be set to the time of the request. This value can be used to create recordings from historical imagery that already exists in the media archive or for pre-scheduling recordings in the future (up to 15 minutes).
tags Comma-delimited list of keyword tags to be added to the recording (optional)

Response

HTTP 201

{"ok": true, "recording_id": "..."}

Download

Retrieve the specified archive file

Request

GET https://api.helios.earth/v1/recordings/:id.:format

Response

HTTP 302 redirect to a signed URL where the jpg, zip, or mp4 file can be retrieved. The signed URL is valid for 15 minutes.

Note: The redirect URL can be followed as-is since it is a signed URL. Do not try to re-add any Helios authorization headers when following the redirect or you will not be able to retrieve the data.

Add Tags

Add keyword tags to an existing recording

Request

PUT https://api.helios.earth/v1/recordings/:id/tags

Body Params

tags Array or comma-delimited list of tags to be added, e.g. ['foo', 'bar'] or 'foo, 'bar'

Response

HTTP 200

{"ok": true, "tags": [...]}