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.

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