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: 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 |
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}