Collections API

The Collections system provides mechanisms for maintaining a discrete collection of imagery datasets, making them consistently indexed and queryable.

Our implementation mirrors the SpatioTemporal Asset Catalog (STAC) standards collections schema and API layout in order to provide support and interoperability for existing tools that utilise this standard.

This can be used to create time series collections of imagery over a single target or site, or to help in discovering what imagery has been previously collected by members of your team, among many other unique applications.

The Collections API consists of 12 endpoints:

List Collections, which will list all collections on your account
Collection Details, which will provide the details of an individual collection
List Collection Items, which will list items (orders and scenes) within the collection
Collection Item Details, which will provide details of an individual item within the collection
Search Collection, which provides query and search functionality to find items within a collection
Create Collections, for creating new data collections
Add Collection item, to add orders to a collection
Remove Collection Item, to remove them from the dataset
Update Collection, to update labelling and descriptive details of the collection
Delete Collection, to delete a collection
Request Item Access, to request access to an order in a collection
Collection Conformance, to view STAC standards compliance of the collection system

Collections List

List all STAC collections the requesting API has access to.

GET: /api/collections?page=1&size=10

Query Parameters

name	data type	purpose
page	number	The page (starting from 0, defaults to 0 if not specified) of data to display, where each page is “size” items in length
size	number	The number of results per page. The default is 100

Response Details

The response object details the list of results, in addition to the query context of the size of the page and number of results returned. Links to related results and the next/previous page may be provided in the attached links.

Copy to Clipboard

The full details of the Collection and Link objects are described in the reference section below

Collection Details

Returns the details of the individual STAC collection with the corresponding ID.

GET: /api/collections/{collection-id}

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved

Response Details

The endpoint returns a full collection object, the full reference for this objects structure is detailed in the reference section below.

Collection List Items

Paginate STAC Items within the collection.

GET: /api/collections/{collection-id}/items?page=0&limit=20&bbox=22,12,23,13&datetime=2022-05-02T12:00:00Z/

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved

Query Parameters

name	data type	purpose
page	number	The page (starting from 0, defaults to 0 if not specified) of data to display, where each page is “limit” items in length
limit	number	The number of results per page. The default is 100
bbox	string	A bounding box to only return results within. Should be 4 numbers separated by commas (,) The elements define the south, west, north and east longitude and latitude boundaries, in that order.
datetime	string	An OAF datetime parameter. This allows for either a single RFC 3339 datetime or an open or closed interval that also uses RFC 3339 datetimes.

Response Details

The response object details the list of items, in addition to the details about total matching items and the number returned. Links to related results and the next/previous page may be provided in the attached links.

Copy to Clipboard

The full details of the Item and Link objects are described in the reference section below.

Collection Get Item

Retrieve an individual item from a collection

GET: /api/collections/{collection-id}/items/{item-id}

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved
item-id	The ID of the item in the collection to be retrieved

Response Details

This endpoint returns a collection item object, the full reference for this objects structure is detailed in the reference section below.

Collection Search Items

Perform a detailed search of items within a collection

GET|POST: /api/collections/{collection-id}/search

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved

This endpoint can be queried both as a GET and a POST request.
A GET request will read the below query parameters for a simple search, whereas a POST request will read the request’s body for the JSON request defined below.

Query Parameters

name	data type	purpose
ids	string	A JSON formatted list of Item ids you wish to retrieve
bbox	string	A bounding box to only return results within. Should be 4 numbers separated by commas (,) The elements define the south, west, north and east longitude and latitude boundaries, in that order.
intersects	string	A JSON formatted GeoJSON geometry object, consisting of the geometry type (point, polygon, etc) and coordinates.
datetime	string	An OAF datetime parameter. This allows for either a single RFC 3339 datetime or an open or closed interval that also uses RFC 3339 datetimes.
query	string	A JSON formatted set of query conditions, see the POST body documentation below for details.
limit	number	The number of results per page. The default is 100
page	number	The page (starting from 0) of data to display, where each page is “limit” items in length (if not specified, the default is 0)

Request Body

Copy to Clipboard

{
    "ids": ["758fbaa6-bcca-4c3e-bf50-50491502263b"],
    "bbox": [
        151.0,
        -34.0,
        151.3,
        -33.7
    ],
    "intersects": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    151.21666172794642,
                    -33.86262071429687
                ],
                [
                    151.21471093542397,
                    -33.86450808965946
                ],
                [
                    151.21719864331902,
                    -33.86655889117889
                ],
                [
                    151.21888097815446,
                    -33.86401767330105
                ],
                [
                    151.21666172794642,
                    -33.86262071429687
                ]
            ]
        ]
    },
    "datetime": "2022-05-02T12:00:00Z/2022-07-30T12:00:00Z",
    "query": {
        "eo:cloud_cover": {
            "lt": 40
        }
    },
    "limit": 30,
    "page": 3
}

name	data type	purpose
ids	string[]	A list of Item ids to be returned
bbox	number[4]	A bounding box to only return results within. Should be 4 numbers separated by commas (,) The elements define the south, west, north and east longitude and latitude boundaries, in that order.
intersects	GeoJSON geometry object	A JSON formatted GeoJSON geometry object, consisting of the geometry type (point, polygon, etc) and coordinates.
datetime	string	An OAF datetime parameter. This allows for either a single RFC 3339 datetime or an open or closed interval that also uses RFC 3339 datetimes.
query	object	A list of field queries to restrict results to matching the provided conditions (see below).
limit	number	The number of results per page. The default is 100
page	number	The page (starting from 0) of data to display, where each page is “limit” items in length (if not specified, the default is 0)

Query options

The query component allows filtering results to those that meet the conditions specified.
Conditions take a structure such as

Copy to Clipboard

Where this example would only allow results with a cloud cover less than 40%.

Each query is made up of the field name of the condition, and contains a set of operations and conditions.

Query conditions are only allowed on certain fields, and this list of which these conditions can be applied to are:

string
The list of entities that provided this item

name	data type	purpose
providers.key
supplier	string	A shorthand alias for the above
platform	string	The identifier for the platform that captured this item
instruments	string	The list of instruments used to capture this item
gsd	number	The ground sample distance of this item (smallest distance is multiple, i.e. from a multi-spectral sensor)
eo:bands.common_name	string	The list of spectral band common names that are available in this item
band	string	A shorthand alias for the above
eo:cloud_cover	number	The percentage cloud cover of this item
eo:snow_cover	number	The percentage snow cover of this item (if provided)
arl:types	string	The imagery types this item contains (i.e. visual, optical, SAR, etc)

The operations that can be performed to constrain results are dictated by the fields data types

For string values like supplier or platform, equality (“eq”) and simple fuzzy match (“like”) are the two operations available, the value for both operator keys should be a string that the item property must equal or pattern match.

For numeric values a broader range of operations are available, such as:

Equality (“eq”)
Less than (“lt”)
Less than or equal to (“lte”)
Greater than (“gt”)
Greater than or equal to (“gte”), or
Within a range “range”

The operator value for each of these should be a number that will be compared against, with the exception of range, which should be an array of two numbers, defining the lower and upper limits of the range.

Response Details

The response object details the list of items, in addition to the details about total matching items and the number returned. Links to related results and the next/previous page may be provided in the attached links.

Copy to Clipboard

The full details of the Item and Link objects are described in the reference section below.

Collection Import Order

Import an order into a collection

POST: /api/collections/{collection-id}/items

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved

Request Body

Copy to Clipboard

name	data type	purpose
order	string	The UUID of an order the API has access to, which should be imported into the collection

Response Details

This endpoint provides no response if successful.

The process of importing an order to a collection is asynchronous, and may take several seconds after this request has returned to become available.

Collection Remove Item

Remove an item from a collection

DELETE: /api/collections/{collection-id}/items/{item-id}

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved
item-id	The ID of the item in the collection to be retrieved

Response Details

This endpoint requires no additional parameters, and returns no value if the request is successfully submitted.

This endpoint is asynchronous, and may take a few seconds for the item to be removed from the collection after responding.

Collection Create

Create a new collection to add imagery to

POST: /api/collections

Request Body

Copy to Clipboard

name	data type	purpose
title	string	A title/name for the collection to identify it
description	string	A description of the collection, such as its purpose, or the location of interest.
keywords	string[]	A list of keywords that describe the collections content for organisational purposes
team	string	The team that will be the owner of the collection (defaults to the requesting API directly)

Response Details

This endpoint will respond with the newly created collection object, see the structure reference below for full details.

Collection Update

Update the details of a collection

POST: /api/collections/{collection-id}

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved

Request Body

Copy to Clipboard

name	data type	purpose
title	string	A title/name for the collection to identify it
description	string	A description of the collection, such as its purpose, or the location of interest.
keywords	string[]	A list of keywords that describe the collections content for organisational purposes

Response Details

This endpoint will respond with the updated collection object, see the structure reference below for full details.

Collection Delete

Delete an imagery collection

DELETE: /api/collections/{collection-id}

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved

This endpoint requires no additional parameters and will not return anything unless an error is encountered removing the collection.

Request Item Access

Request access to an item in the collection that the caller does not have resource access permission to.

POST: /api/collections/{collection-id}/{item-id}/access-request

Path Parameters

name	purpose
collection-id	The ID of the collection to be retrieved
item-id	The ID of the item in the collection to request access to

Request Body

Copy to Clipboard

name	data type	purpose
team	string	(optional) the UUID of the team to grant access to, rather than the requestor (must be a member of the team)
message	string	A message to present to the item owner, stating the reason for requesting access. Only alphanumeric, spaces and basic symbols (: _ \ – , . / ‘ # $ % ^ & *) are permitted.

Response Details

This endpoint provides no response if successful in sending the access request.

Collection Conformance

The conformance endpoint is a required component of the STAC standard, and lists the set of JSON Schema documents that the API and its output data is in conformance with. These schemas often indicate support for some extension upon the base STAC specification.

GET: /api/collections/conformance

Response details

The response to this endpoint is an envelope object, and a list of URI pointing to JSON Schema documents

Copy to Clipboard

Collection Object

Many of the collections endpoints return the top level collection object.
It’s structure looks like the following:

Copy to Clipboard

Fields

name	data type	purpose
id	string	The unique identifier for this collection
type	string	Part of the STAC standard to conform with GeoJSON, will always be “Collection”
stac_version	string	The version of the STAC standard being adhered to
stac_extensions	string[]	A list of STAC extension schemas this collection complies with
title	string	A descriptive title of the collection
description	string	A more detailed description of the collection and its contents
keywords	string[]	Identifying keywords for the collection
license	string	SPDX License identifier, various if multiple licenses apply or proprietary for all other cases
providers	Provider[]	A list of providers that are the source of or that manage data in this collection
extent	Extent	The spatial and temporal extents of items in this collection
assets	Asset Map	A list of any assets related to this collection but not to any specific items within it
summaries	Summary Map	Summaries of the range or values of common properties of items in this collection
links	Link[]	Links to resources and media associated with this collection

Collection Provider Object

The provider object provides details about the source and management of data items and collections as a whole
It’s structure looks like the following:

Copy to Clipboard

Fields

name	data type	purpose
name	string	The name of the provider
description	string	A description of the provider and their data
roles	string[]	A list of providing roles they fulfil (i.e. licensor, producer, processor or host)
url	string	Link to the providers homepage

Collection Extent Object

The extent provides information about the distribution of data in a collection both spatially and temporally.

It provides lists of extents, with the first being the total extent of the collection as a whole, and optionally additional ranges within that, if the data is distributed in independent clusters of space or time.

It’s structure looks like the following:

Copy to Clipboard

Fields

name	data type	purpose
spatial	object	wraps the spatial extents of the collection
spatial.bbox	number[4][]	a list of bounding boxes representing spatial data extents within the collection (with the first being total extent of all data)
temporal	object	wraps the temporal extents of the collection
temporal.interval	string[][]	a list of time intervals with a start and end date (or null for an open interval) where the first entry will be the total temporal extent of all data in the collection

Collection Asset Object

Assets represent a discrete file resource associated with a Collection or Item, and provides the details for its retrieval.
It’s structure looks like the following:

Copy to Clipboard

Fields

name	data type	purpose
href	string	Url of the asset
title	string	Title or name of the asset
description	string	Optional description of the asset
type	string	IANA media type (MIME type) of the asset
roles	string[]	List of semantic roles this asset satisfies (see resource reference for more details)

Collection Link Object

Collections, Items and various endpoints return Link objects, which provide links to related media and content of the response, or object, and where it can be retrieved.
It’s structure looks like the following:

Copy to Clipboard

Fields

name	data type	purpose
href	string	The URL of the linked media
rel	string	The type of relationship the media has to the current document. (i.e. parent, next result, the associated licence. etc)
type	string	The IANA Media Type (MIME) of the linked media
title	string	An optional title to describe the linked media

Collection Summary Object

The Collection summary provides information on the range of values found for a given field within the collection.

Each key in the summary object matches a field found in Item properties, and provides a summary for the different values that can be found within the collection.

There are three main forms a summary entry may take:

a range from a minimum to a maximum,
a list of values found, or
a JSON schema document (this is not used by default, unless you have custom processing to facilitate it)

It’s structure looks like the following:

Copy to Clipboard

Where platform is summarised as a list of valid values, and gsd as a numeric range.

Collection Item

Many of the collections endpoints return collection Items representing a capture event
It’s structure looks like the following:

Copy to Clipboard

{
    "type": "Feature",
    "stac_version": "1.0.0",
    "stac_extensions": [
        "https://api.stacspec.org/v1.0.0/core",
        "https://api.stacspec.org/v1.0.0/ogcapi-features",
        "https://stac-extensions.github.io/view/v1.0.0/schema.json",
        "https://stac-extensions.github.io/projection/v1.0.0/schema.json",
        "https://stac-extensions.github.io/eo/v1.0.0/schema.json",
        "https://stac-extensions.github.io/file/v1.0.0/schema.json"
    ],
    "id": "6337e11d-6023-409c-84f7-2be5cf7b709d",
    "bbox": [99.38146230542348,4.8558167064330675,101.44793714417807,6.706212156396265],
  	"crs": "EPSG:4326",
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [99.71859320598271, 6.706212156396265],
                [99.38146230542348, 5.108949840670607],
                [101.10598403768917, 4.8558167064330675],
                [101.44793714417807, 6.454166316752566],
                [99.71859320598271, 6.706212156396265]
            ]
        ]
    },
    "properties": {
        "datetime": "2008-08-21T03:19:45.295044Z",
        "eo:cloud_cover": 45,
        "view:sun_azimuth": 76.15590371,
        "view:sun_elevation": 59.31861633,
        "platform": "LANDSAT_5",
        "instruments": [
            "TM"
        ],
        "view:off_nadir": 0,
        "proj:epsg": 32647,
        "proj:shape": [6911,7881],
        "proj:transform": [30,0,538185,0,-30,742515],
        "created": "2022-06-28T23:43:38.918Z",
        "updated": "2022-06-28T23:43:38.918Z"
    },
    "assets": {
        "thumbnail": {
            "title": "Thumbnail image",
            "type": "image/jpeg",
            "roles": [
                "data",
                "raster",
                "thumbnail"
            ],
            "href": "s3://usgs-landsat/collection02/level-1/standard/tm/2008/128/056/LT05_L1TP_128056_20080821_20200829_02_T1/LT05_L1TP_128056_20080821_20200829_02_T1_thumb_small.jpeg",
            "file:checksum": "13405a7b0312d50e5af86d105ccaacdd5a2d817f9be401777ec80ccafa0606b219f6acd07d278bc664dc7751c991922d71c8cd63e4a2e4b624174a986bbbad30f04d"
        },
        "blue": {
            "title": "Blue Band (B1)",
            "description": "Collection 2 Level-1 Blue Band (B1) Top of Atmosphere Radiance",
            "type": "image/vnd.stac.geotiff; cloud-optimized=true",
            "roles": [
                "data",
                "raster",
                "blue"
            ],
            "eo:bands": [
                {
                    "name": "B1",
                    "common_name": "blue",
                    "gsd": 30,
                    "center_wavelength": 0.49
                }
            ],
            "href": "s3://usgs-landsat/collection02/level-1/standard/tm/2008/128/056/LT05_L1TP_128056_20080821_20200829_02_T1/LT05_L1TP_128056_20080821_20200829_02_T1_B1.TIF",
            "file:checksum": "13409b9a2ff83dbb5e7af59e6f3a96fe4314681abb029584daa20ecb0736e00701d7c3b1a894413e16dd4b59ce4a5e62319c17f30151c48e5aa2e3bceac4009d01bd"
        }
    },
    "links": [
        {
            "rel": "self",
            "href": "https://api.arlula.com/api/collections/30f0fce1-54f3-4e1a-b51c-77bb40cc408d/6337e11d-6023-409c-84f7-2be5cf7b709d"
        },
        {
            "rel": "parent",
            "href": "https://api.arlula.com/api/collections/30f0fce1-54f3-4e1a-b51c-77bb40cc408d"
        },
        {
            "rel": "collection",
            "href": "https://api.arlula.com/api/collections/30f0fce1-54f3-4e1a-b51c-77bb40cc408d"
        },
        {
            "rel": "root",
            "href": "https://api.arlula.com/api/collections"
        }
    ],
    "collection": "30f0fce1-54f3-4e1a-b51c-77bb40cc408d"
}

Fields

name	data type	purpose
type	string	Part of the STAC standard to conform with GeoJSON, will always be “Feature”
stac_verions	string	The version of the STAC standard being adhered to
stac_extension	string	A list of STAC extension schemas this item complies with
id	string	ID of the order the item corresponds to
crs	string	The Coordinate Reference System for all geometry of this item (unless otherwise specified). Represented either as a EPSG code, or GDAL Well Known Text if no EPSG code is identified.
geometry	GeoJSON Geometry	The polygon defining coverage of this item in the given CRS.
bbox	number[]	The total bounding box of the item
properties	Properties Object	The list of properties of this item (see above)
links	Link[]	Links to resources and media associated with this collection
assets	Asset Map	A list of any assets related to this item, including all resources from the source order
collection	string	The ID of the collection this item is from