Note: The Collections API is currently in beta and is subject to frequent changes.

Collections API

The Collections API allows users to group and organize individual image frames.

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


Index

Return a list of collections matching the provided text or metadata filters

Request

GET  https://api.helios.earth/v1/collections  or
POST https://api.helios.earth/v1/collections/_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
created_at_min, created_at_max Creation time, specified in UTC as an ISO 8601 string (e.g. 2013-07-01 or 2013-07-01T12:34:56.000Z).
updated_at_min, updated_at_max Last update 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: name, created_at, updated_at 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: tags.


Aggregations can be requested using array syntax or as comma-delimited, e.g:

aggs[]=tags
aggs=tags

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

Response

{
  "results": [
    {
      "_id": "my-collection",
      "name": "My collection",
      "description": "My favorite images",
      "tags": ["foo", "bar"],
      "created_at": "2016-08-01T12:34:56.789Z",
      "updated_at": "2016-08-01T12:34:56.789Z"
    },
    ...
  ],
  "total": 100,
  "skip": 0,
  "limit": 10,
  "aggs": {}
}

Show

Return the attributes and image list for a single collection

Request

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

Query Parameters

limit Number of image names to be returned with each response. Defaults to 20. Max value of 200 is allowed.
marker Pagination marker. If the marker is an exact match to an existing image, the next image after the marker will be the first image returned. Therefore, for normal linked list pagination, specify the last image name from the current response as the marker value in the next request. Partial file names may be specified, in which case the first matching result will be the first image returned.

Response

{
  "_id": "my-collection",
  "name": "My collection",
  "description": "My favorite images",
  "tags": ["foo", "bar"],
  "created_at": "2016-08-01T12:34:56.789Z",
  "updated_at": "2016-08-01T12:34:56.789Z",
  "images": [
     ...,
     "my-collection-image.jpg"
  ],
  "limit": 20,
  "marker": ""
}

Create

Create a new collection

Request

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

Body Params

name Display name for the collection
description Description for the collection
tags Comma-delimited list of keyword tags to be added to the collection (optional)

Response

200 {"ok": true, "collection_id": "..."}

Update

Update a collection

Request

PATCH https://api.helios.earth/v1/collections/:id

Body Params

name, description, tags

Response

200 {ok: true}

Show Image

Return a single image from a collection

Request

GET /collections/:id/images/:name

Response

302 redirect to a signed URL where the image 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 Image

Add a single image to a collection

Request

POST /collections/:id/images

Body Params

Specify one of the following sets of params, based on the type of image to be collected.

camera_id Add the current image from a camera to the collection by specifying the camera ID.
camera_id, time Add an image from the media archive by specifying the camera ID and an exact image time. Time is specified in UTC as an ISO 8601 string (e.g. 2016-08-01T12:34:56.789Z).
observation_id Add the preview image from an observation by specifying the observation ID.
recording_id Add the preview image from a recording by specifying the recording ID.
recording_id, image Add an image from an existing recording sequence by specifying the recording ID and the image name.
collection_id, image Add an image from another collection by specifying the source collection ID and the image name.

Response

200 {ok: true}

Remove Image

Remove a single image from a collection

Request

DELETE /collections/:id/images/:name

Response

200 {ok: true}

Preview

Return a preview image for the collection

Request

GET /collections/:id/preview

Response

302 redirect to a signed URL where the image 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.


Empty

Bulk remove (up to 1000) images from a collection

Request

DELETE /collections/:id/images

Response

200 {ok: true, total: 1000}

Destroy

Delete an empty collection. Use the empty method to remove all imagery before calling this method.

Request

DELETE /collections/:id

Response

200 {ok: true}