API Documentation

Overview

The Arlula infrastructure is broken down into a few main sections, each relating to distinct actions including accessing, purchasing, managing, and utilising satellite imagery data from archival and tasking sources.

This documentation serves as a comprehensive resource to best understand the platform and its associated endpoints.

If you would instead rather work with an SDK in your preferred language, we have a Python and NodeJS SDK available. If you are using another language, please let us know.

General information about authentication and connection testing can be found below, along with a changelog for major updates.

The following are the four main API groups, and their main endpoints:

Archive API: for querying and purchasing satellite imagery captured some time in the past.
This includes the ability to:

Search, for obtaining a list of satellite imagery available for the request’s search criteria
New order, which creates a new order, and pays for purchasing imagery
Batch Order, for ordering multiple scenes at the same time

Tasking API: for querying availability and ordering satellite imagery to be captured in the future.

Search, for obtaining a list of possible capture opportunities for a target location, time period and conditions
Order, for confirming and booking one of the opportunities obtained from search
Batch Order, for confirming and booking a set of tasking opportunities in a single operation.

Orders API: for managing and downloading your past imagery orders.

List orders, which will list all past and current orders on your account
Get order, which will list the details and any associated resources of an order on your account
Get resource, which requests download of a resource associated with an order, such as the imagery or its metadata

Collections API: for creating and managing collections of imagery that can be queried and explored as a discrete dataset.

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

API Authentication

Making requests to the Arlula APIs requires providing API Authentication credentials for every request as part of the request header.

To obtain API credentials, you will need to create and API account in our system dashboard and be issued with API Credentials.

All requests to the API must be made via a https connection

Authentication is achieved by providing your API Key and API Password using the HTTP Basic Auth Mechanism.

Connection Testing

An endpoint is available at /api/test that does nothing other than check your authentication.

This is often useful if you want to check your setup prior to making actual requests.

Changelog

Version 1.0.0:

Initial version of API, supported:

search imagery
order imagery
orders list
order get
order
resource get

Version 1.1.0:

Internal update for platform update:

added signature management internal api
added admin pages to manage orders

Version 1.2.0:

Added SI Imaging as an imagery supplier/vendor

Version 1.3.0:

Added signup procedure for non activated accounts

Version 2.0.0:

AOI ordering for imagery
Search response structure changed:

added sceneID field
added annotations
field – changed overlap to object with children:
- area
- percent
- polygon
Changed price field to include new field aoi which also contains pricing information for AOI order

Order object changes:

added trim field

Version 2.0.1:

Added new resource types:

`img_jp2` for JPEG Core 200 format imagery, and
`meta_bundle` for aggregated or otherwise bundled metadata

Version 2.0.2:

Updated order status labels to clarify state (‘manual’ for awaiting supplier non-automated response caused confusion)

Version 2.0.3:

Added additional resource types for scene geometry:

geo_json for geometry defined in the geoJSON standard
geo_kml for geometry defined in Keyhole Markup Language (KML)
geo_shp for bundled shapefiles and their metadata (zip file containing shp, shx, dbf and prj files)
geo_bundle for geometry of a unknown or miscellaneous format provided by the supplier

Version 2020-12:

Change in version number format (2020-12 rather than 3.0.0.
Coordinates in a point are reversed order to be [long, lat] to be consistent with geoJSON and similar formats as an X, Y format.
API account delete functionality.
Webhook events now have a wrapper to their payload to support future planned usage
MOQ ordering; all searches return an AOI price, increased to the supplier minimum order if it was less than it. This causes several dependent changes:
- overlap field is always included and includes the polygon that will be ordered
- overlap.percent is now an object with two fields search and scene
- price is now a single pricing object that provides the AOI price, scene pricing is no longer provided
- remove trim as an ordering parameter

Version 2021-01

Added additional server behaviors to enable UI’s binding against the API (internal, version bump for bug tracking)

Version 2021-03

Supplier search filter support
Change to ordering ID encoding standard to support future planed features

Version 2021-09

Added cloud cover archive search filter
Added off nadir archive search filter
Added offNadir to archive search results
Added platform to archive search results
Updated resource structure, adding roles, format, size and checksum fields

Version 2022-07

Archive search request “res” parameter renamed to “gsd”
Archive search response is now object rather than result array
Removed archive search result eula and price fields
Renamed archive search result field “id” to “orderingID” and “resolution” to “gsd”
Increased polygon arrays to depth 3 for archive search result “bounding” and “overlap.polygon” to support complex polygons
Added new archive search result fields “bands” for spectral resolution information, “bundles” for ordering level selection, and “licenses” for licensing selection.
Deprecated “seats” as a field on archive order request
Added “bundleKey” in archive order request to select processing level by key
Order structure “imageryID” field renamed to more representative “orderingID”

Version 2023-01

support to search by polygon

Version 2023-06

batch archive ordering
archive search via POST request
collections system

Version 2023-08

Tasking API
Archive search sort parameter