Tasking API

The Tasking API provides endpoints to view available capture opportunities and purchase capture capacity with suppliers for imagery to be captured at a future date based on your requirements.

The Tasking API consists of 3 endpoints:

  • 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.

Tasking Search

The tasking search endpoint facilitates searching of Arlula and its supplier’s capturing capacity.

POST: /api/tasking/search

The tasking search can be constrained by a start time, end time, gsd, off nadir, and geometry.

The start and end times will constrain results to any intersecting availability. Where possible results will start at the specified start time and end at the specified end time, however this can be impacted by the following considerations:

  • Supplier minimum notice period. Many suppliers have a set minimum time in the future
  • Supplier maximum notice period.
  • Supplier minimum time span.
  • Supplier maximum time span.

The geometry can be provided by one of polygon, boundingBox, or latLong, which respectively detail a polygon, extent, or point of interest.

It will respond with a list of results that coincide with the specified search. Each result is indicative of purchasable capturing capacity with a specific supplier and platform, between the returned start and end date, and at a maximum off nadir.

Interest Area

There are currently three ways of providing a tasking search interest area:

  • A point of interest
    Define a point of interest by providing the `latLong` object, including `latitude` and `longitude`. This will be the centre of search.
  • A bounding box defining an area of interest.
    Define a bounding box by providing the `boundingBox` object, including `north`, `south`, `east`, and `west`. The centre of this bounding box will be the centre of search.
  • A polygon defining an area of interest.
    Define a polygon by providing the `polygon` field on search. This should be a non-self intersecting WGS84 polygon.

Tasking Search Request:

Copy to Clipboard
name data type purpose
start Datetime in RFC3339 The start time of the period of interest. Must be in the future.
end Datetime in RFC3339 The end time of the period of interest. Must be in the future and after start.
gsd A positive number The nadir gsd of the sensor.
latLong latLong object
polygon JSON array
boundingBox boundingBox object
offNadir A positive number less than 30. (optional) The maximum off-nadir acceptable for capture. Results will not have an off nadir greater than this.
sort A Sorting descripting (see below). (optional) the desired field to sort results by, and if that sort should be ascending or descending

LatLong Object

The LatLong object details a target point.

name data type purpose
latitude Number between -90 and 90. Latitude of interest
longitude Number between -180 and 180. Longitude of interest

Example:

Copy to Clipboard

BoundingBox Object

Describes an area

name data type purpose
north Number between -90 and 90 degrees. northern most extent of the area
south Number between -90 and 90 degrees. southern most extent of the area
east Number between -180 and 180 degrees. eastern most extent of the area
west Number between -180 and 180 degrees. western most extent of the area

Example:

Copy to Clipboard
Sorting Results

Results can be sorted by specifying the “sort” parameter, by default, if no method is specified, the default sorting method will be applied.

The sort parameter takes an object with two inner parameters,

name data type purpose
field string The field to sort by
ascending boolean Whether the sort should be ascending or descending in order
Copy to Clipboard

The supported fieldnames are:

  • duration
  • supplier
  • start
  • end
  • maxOffNadir
  • areas.scene
  • areas.target

Response Details:

The results of a tasking search will be returned as a Tasking Search Response structure

The full details of this structure are available in the reference section below, but an example response would resemble the following:

Copy to Clipboard

Tasking Order

The tasking order endpoint facilitates ordering and paying for tasked imagery from Arlula and it’s suppliers.

POST: /api/tasking/order

It is to be used on results of the Tasking Search endpoint.

Query Body:

Copy to Clipboard

Example body:

Copy to Clipboard

A full reference for the structure can be found in the reference section below

Response Details

The /api/tasking/order endpoint returns a JSON encoded response consisting of a Order object, with a structure like the following structure:

Copy to Clipboard

A full reference for the structure can be found in the reference section below

Batch Tasking Order

The tasking batch order endpoint facilitates ordering and paying for multiple tasked imagery from Arlula and it’s suppliers at the same time.

POST: /api/tasking/order/batch

It is to be used on results of the Tasking Search endpoint.

Query Body:

Copy to Clipboard

Example body:

Copy to Clipboard

The batch request acts as a wrapper for several order requests allowing submission of multiple orders, while also defining the defaults for settings like team to avoid repetition.

Top-level properties will be applied to individual orders differently:

  • webhooks, emails and delivery collections will be appended to any specified on the individual orders,
  • team and delivery location will be set on any orders where they are not otherwise set,
  • coupon and payment will apply to all orders, overriding individual orders, as batch orders are billed as a single payment event.

A full reference for the order request structure can be found in the reference section below

Response Details

The /api/tasking/order/batch endpoint returns a JSON encoded response consisting of an array of Order objects, with the following structure:

Copy to Clipboard

A full reference for the order object’s structure can be found in the reference section below

Tasking Search Response Object

Tasking results will contain a list of results, and optionally errors returned by suppliers.

This will result in a structure as follows:

Copy to Clipboard

Result Areas

name data type purpose
Scene Number, square kilometers The estimated deliverable scene size.
Target Number, square kilometers The target polygon size.

Bundles

name data type purpose
key string The bundle key that is to be provided to the order endpoint to purchase this bundle
bands string[] The list of bands included in this level as a list of the bands “id” property (see bands above),
if the list is empty, all bands are provided.
price number The base price for this bundle in US cents

Licenses

name data type purpose
name string A human readable name to refer to this license type (i.e. “internal”, or “enterprise”)
href string A URL at which the terms of the license can be read, use this value in the ordering endpoints “eula” field to select this license for ordering
loadingPercent number The percentage loading this license applies to the bundle’s price
loadingAmount number The static amount (in US cents) this license adds to the bundle’s price

Tasking Search Response

The tasking search response details

name data type purpose
results []Tasking Search Result Objects Details candidate tasking opportunities.
errors []Error Details reasons why suppliers could not fulfil the requested tasking.

Tasking Search Result

name data type purpose
polygons 4d floating point array Each polygon represents a single orbital pass which could be captured, with the full set showing the coverage requested from the supplier.
startDate Datetime in RFC3339 The start time for an order created from this result. It may be later than the searched start time, depending on the supplier’s minimum notice period.
endDate Datetime in RFC3339 The end time for an order created from this result. It may be earlier than the searched period, depending on the supplier’s maximum notice period.
areas Areas object Container for area information including estimated scene area and target area.
gsd number The nadir GSD for this result.
supplier string The supplier that provides this capture opportunity.
orderingID string The OrderingID for this result. Pass this to the ordering endpoint, along with a suitable bundle key and license eula to order this result.
offNadir number The maximum off nadir requested for this result.
bands []Band object List of the Spectral Bands captured in this scene, see below
bundles []Bundle Option object Ordering bundles representing the available ways to order the imagery, see below
licenses []License Option object License options this imagery may be purchased under, and the terms and pricing that apply, see below
platforms String array A list indicating the satellites and/or constellations that will fulfil this request.
annotations String array Annotates results with information, such as what modifications were made to the search to make it valid for this supplier.

Bands

name data type purpose
name string the common name of the band frequently used to identify it in a human readable manner (i.e. “Red” or “Short Wave InfraRed”)
id string A short form identifier for the band used to identify the band in references.
min number the minimum wavelength that makes up the band in nanometers (nm)
max number the maximum wavelength that makes up the band in nanometers (nm)

Error

name data type purpose
supplier string The supplier that was unable to satisfy the search.
platforms []string The platforms that were unable to satisfy the search.
message string The reason why they were unable to satisfy the search

Order Request

The /api/tasking/order endpoint requires a JSON object specifying the order details, which resembles the following:

Copy to Clipboard

Object Parameters

name data type purpose
id string unique ID of the imagery to purchase, provided in the search endpoint
eula string the eula string provided in the search results to confirm acceptance
bundleKey string the key of the bundle you wish to purchase from the scene
webhooks array (optional) a list of http/https addresses (strings) that the order details will be sent to once the order is complete and ready for collection
emails array (optional) a list of email addresses (strings) that the order details will be sent to once the order is complete and ready for collection
team string (optional) the ID of the team to attach the order to, if other than the default team for the API (used to control shared access to the order)
coupon string (optional) string coupon code to apply to discount the order pricing
payment string (optional) the ID of the payment method to charge this order to (if not free). If not specified, the APIs default billing method will be charged.
delivery string (optional) Define a set of delivery configuration parameters for cloud delivery, and default collections the order should be added to (see below).

Webhooks and Emails

Your API can be notified of your order being complete by providing either a webhook and/or email address, to which the order details, and its resource list, will be provided when the order is complete.

Emails will receive a human readable message informing them of the order completion, with the orders details and resource list included.

Webhooks will receive a http POST request which will be sent to the provided address with an event wrapper with the structure of

Where the payload object will be a detailed order object (as returned by this and the Order Get endpoint).

Note: At this time, webhooks provided through the tasking order endpoint itself will only receive "tasking.order.complete" events when the order is complete. Other events will be supported in the future, mostly through the API level webhook configuration rather than per order.

Delivery Configuration

The delivery field allows specifying order delivery behaviour for this order, allowing for delivery to your cloud storage (only AWS S3 is supported at this time), or which dataset collections the order should be added to upon completion.

Copy to Clipboard
name data type purpose
location string uri a S3 URI to deliver the data to, upon order completion (note, the bucket must have role based authentication allowing arn:aws:iam::293050344299:role/delivery-task-runner to write to the specified location).
collections uuid[] A list of IDs of collections to which the order should be added to upon completion, in addition to any specified by team or organisation policy.

Order Object

The order object is a JSON object, that resembles:

Copy to Clipboard

Order Parameters

name data type purpose
id string UUID to uniquely identify the order
createdAt string datetime the order was created at (UTC timezone)
updatedAt string datetime of the last update to the order (UTC timezone)
supplier string supplier providing the imagery
orderingID string ID used to order the imagery
sceneID string suppliers scene ID to identify the order
status string current status of the order (see below for values)
total number total price of the order in US cents
type string order type designation (archive, tasking, custom, event orders; scene v aoi orders)
expiration nullable string timestamp for order expiration (see below for details)
resources array lists the resources available for download on the order (see below)

NOTE: the resources array will be omitted if there are no resources available for the order yet, or if the order is not complete.

Status codes

The order, once created may return several different status codes to indicate its current state of completion.

value meaning
created The order has been created and is queued for sending. This state will normally never be returned by the API
pending The order has been created and is awaiting confirmation of placement from the supplier
processing The order is awaiting delivery of imagery from the supplier
post-processing The order is undergoing additional processing of the imagery to fulfil the order
complete The order is complete and its imagery may be downloaded via the `order/resource/get` endpoint
manual This status only applies to custom orders delivered under contract and will not normally appear in the API

Order expiration

Orders, once complete are retained in storage for 1 month from completion/delivery. After this date the orders resources are no longer available for delivery/retrieval from the user interface or order/resource/get endpoint.

The expiration field of an order identifies the date and time after which resources will not be retrievable. The field will be a JSON null under the following conditions:

  • The order is not yet complete, expiration will start once the order is complete
  • The order is from a public dataset such as the landsat or sentinel missions and will not expire

Resource Object

Completed orders will have at least one resource available to download that provides the requested imagery.

Each Resource has structure like the following:

Copy to Clipboard

Resource Fields

name data type purpose
id string ID for the resource, used to request download of the resource
createdAt string datetime the order was created at (UTC timezone)
updatedAt string datetime of the last update to the order (UTC timezone)
order string UUID of the order to which this resource belongs
name string name of the resource (often a filename)
type string Legacy type of resource (see below)
format string MIME type of the file, such as image/png, or application/json
(see roles reference for common examples)
roles string[] list of roles this file fills in hierarchial order from general to specific
(see below for reference)
size integer File size in bytes
checksum string Checksum for the file to facilitate integrity checking.
will be in the form :.
At time of writing, format is either MD5 or SHA1.

Common Formats

Imagery and it’s metadata can be delivered in a variety of file formats, with the specific choice of format often varying with supplier.

The resource format field provides details about the format a given resource file is in, in the form of a MIME type.

The following is a summary of the most common formats returned by suppliers (with a few less common but important edge cases):

format details
image/tiff; application=geotiff A ‘geoTiff’, a tiff image with geographic and geo-referencing metadata attached, the most basic, and common type of imagery.
image/tiff; application=geotiff; profile=cloud-optimized A ‘Cloud Optimized Geotiff’ or COG for short.
A special subcategory of ‘geotiff’ that internally has a tiling structure and an overview pyramid for easier atomic retrieval of data.
There are several proposed MIME types for COGS, this was the most recent official proposal at time of writing, unless another value is officially adopted, this will be the value used to ensure backwards compatibility.
image/jp2 The JPEG Core 2000 image format
Has several similar features to the COG format, but less popular at this time.
image/jpeg
image/png
Common image formats, able to be viewed in browsers, though featuring compression that results in data loss.
Frequently used for thumbnails or similar overview data.
application/geo+json Official MIME for geoJSON, a JSON based notation of vector/feature data.
application/zip ESRI Shapefile
This format is a special case.
This format should only be found on resources with a vector type.
As the ESRI Shapefile format consists of multiple files, to ensure they are all acquired together in a download, they are zipped together.
application/json JSON encoded metadata for the capture scene
application/xml XML encoded metadata for the capture scene
text/MTL text based MTL encoding of metadata, often seen from NASA landsat captures.
text/plain Plain text file, often used for license information in a scene
application/pdf A portable document format (pdf) file, often used for license information in a scene

Legacy Resource Types

The type field is a legacy of past versions of the API.

It is maintained for legacy support, new users are recommended to use the new format and roles fields instead (see below).

The returned legacy types are

value meaning
img_tiff default imagery label, geoTIF imagery for the requested area
img_jp2 JPEG Core 200 format imagery for the requested area
thumb low resolution thumbnail imagery in jpg or similar format
gdal_tiff_overview .tif.ovr file used by GDAL applications
meta_mtl metadata in text-based mtl format
meta_json metadata in JSON format
meta_xml metadata in XML format
meta_bundle bundled metadata file(s) provided by the supplier
geo_json scene or order geometry data in the geoJSON format
geo_kml scene or order geometry data in the Keyhole Markup Language
geo_shp scene or order geometry data in a zip of a shapefile
license a license/terms declaration file, usually plaintext

NOTE: not all suppliers return data in all types, and a single imagery request may contain multiple files of the same type (i.e. multiple img_tiff resources for different imaging bands on the satellite).

Integrity checking and checksums

Resources downloaded from the API, as with any message over the internet, may be altered or corrupted in transmission.
To aid in detecting such scenarios, a checksum is provided for all resource.

Each resources checksum consists of 2 parts, separated by a colon character (:)
The first part identifies the type of checksum, currently this is either MD5 of SHA1.
The second part is the base64 encoded hash of the resource body.

With this, downloaded resources can be similarly hashed and the value checked against the reported value of the resource.

Resource roles

Roles form a hierarchical tree describing the contents of a given resource

Roles should be read from start to end as being from least to most specific descriptor

The following details the common hierarchies of roles for most order resources:

“data”

Main product data for order.
Resources with this role are often the largest, and contain the primary data sources.

Data generally comes in 3 types

  1. “raster” resources are traditional pixel images
  2. “vector” resources are geographic features like points, polygons and features
  3. “structured” resources are information in machine readable data formats like JSON

At this time, primary data is only returned with the raster, however vector and structured are reserved for future use.

> “raster”

Raster data is the primary deliverable for satellite imagery orders at this time.
These roles describe the type of raster data a given resource is.

>> “reflectance”

reflectance data is light reflected from the observed surface in the relevant band

Below this level roles become less hierarchical.

First describing the band(s) present in the file. If the file is a single band, the next role will be the common name for that band. If instead the resource contains multiple bands, it will have the multi-band role, followed by the list of band common names, in the order they appear in the resource/

Using the band common name the corresponding band information can be found in the metadata file with the bands role.

Some special case “pseudo” bands exist which may be found here in custom orders. These generally correspond to some standard processed raster band such as ndvi and similar. Despite being processing, they are included before other processing roles as they occupy a band in the file

Lastly, if there is processing of the imagery that may affect selection between several similar/related files, it is included as the final set of roles. This is generally large processing jobs which produce distinct artifacts, such as the following:

    • pansharpened for pansharpened imagery
    • orthorectified for orthorectified imagery
    • radiometrically-corrected for imagery that has undergone radiometric correction
    • mosaic for cases where a mosaic has been produced from multiple source images

Example: [“data”, “raster”, “reflectance”, “multi-band”, “red”, “green”, “blue”, “nir”, “pansharpened”]

>> “temperature”

Thermal reflectance data from a thermal sensor like landsat-8’s TIRS sensor.

Example: [“data”, “raster”, “temperature”]

>> “overview”

If the primary data format does not support internal overviews, they may be provided as a separate file identified by this role.

Example: [“data”, “raster”, “overview”]

>> “browse”

A full resolution image of the scene in a more compact format such as JPEG or PNG. These files may have lossy compression and/or compression artifacts and not represent the true data. They are intended as summary data when needed.

Example: [“data”, “raster”, “browse”]

>> “thumbnail”

A low resolution overview of the whole area of interest, generally “true color” or RGB if the image is has the relevant bands.

Example: [“data”, “raster”, “thumbnail”] > “vector”

Not supported at this time, but reserved for future use.

> “structured”

Not supported at this time, but reserved for future use

“metadata”

Descriptive metadata that provides information about the primary data.

Metadata generally comes in 3 types

  1. “raster” resources are traditional pixel images, describing a value at each pixel location
  2. “vector” resources are geographic features such as the polygon within which is valid data, or where the seams of adjacent tiles are
  3. “structured” resources are information in machine readable data formats like JSON, such as general information about a capture; such as the date of capture, or how the scene was processed

> “raster”

Raster metadata often describes values for a scene that correspond to each pixel in the primary data.
such as whether each pixel is classified as being cloud cover, or the azimuth angle for each pixel.

Raster metadata files often fill multiple roles, with each band being a different piece of metadata.
As such, the subsequent roles form a list of what metadata is found in the file
i.e. a single resource may have the cloudcloud-shadow and water-mask roles for a roles array of ["metadata", "raster", "cloud", "cloud-shadow", "water-mask"]

Note: effort is made to ensure that the role order matches a files band order, however this may not always be the case. Please let us know if you find any discrepancies

The descriptions below describe the meaning of each role for a given pixel in this metadata file

role meaning
saturation Indicates that the given pixel was saturated in capture, the real value is outside the measured range
cloud Indicates that the given pixel has been categorized as being cloud cover
cloud-shadow Indicates that the given pixel has been categorized as being shadowed by a nearby cloud
snow-ice Indicates that the given pixel has been categorized as either snow or ice cover on the ground
land-water Indicates whether the given pixel has been categorized to be land or water
terrain-shadow Indicates that the given pixel has been categorized as being shadowed by nearby terrain
terrain-occlusion Indicates that the given pixel has been categorized as being occluded by some other terrain feature.
(Generally only relevant to orthorectified scenes)
terrain-illumination Identifies the coefficients used for terrain illumination correction
incidence-angle The incidence angle between the pixel’s ground point and the sensor
azimuth The azimuth angle between the pixel’s ground point and the sensor
sun-azimuth The azimuth angle between the pixel’s ground point and the sun
sun-elevation The elevation angle between the pixel’s ground point and the sun

Example: [“metadata”, “raster”, “land-water”, “cloud”, “cloud-shadow”, “snow-ice”]

> “vector”

Vector metadata often describes details about the imagery, such as a summary of its location, or that of the larger scene it belongs to, how the imagery was built from tiled captures, or how the delivery files themselves are tiled.

>> “reference”

Reference vectors describe details about data location

It is followed by a role identifying what it is a reference for

Currently it may be a reference for either:

    • scene in which case it is the boundary for the whole source scene of the imagery, or
    • aoi to identify the location boundary of the delivered Area Of Interest

Example: [“metadata”, “vector”, “reference”, “aoi”]

>> “tiling”

Tiling metadata files describe how multiple data files in an order relate to each other in space

If present, these are often the preferred way to load the imagery, we they can provide metadata about the scene which prevents artifacts such as color balance issues.

These will often be found as GDAL Virtual Raster Table (.vrt) files, or TILE files (.til)

Example: [“metadata”, “vector”, “tiling”]

>> “scene-tiles”

Scene tiles describe the boundaries and tiling of source imagery that makes up a scene (such as when a satellite has multiple overlapping CCD’s)

Example: [“metadata”, “vector”, “scene-tiles”] > “structured”

Structured metadata files provide information about an order and its source scene
This information can provide more context for a scene, or information necessary to process it.

role meaning
files An optional metadata file identifying the files in the delivery,
Most commonly used if delivering to customer storage
(generally mirroring an orders resource list)
general General metadata about a capture, such as date of capture, projection, averages of values like azimuth and incidence angle, etc.
ephemeris Ephemeris data identifies the satellites position and velocity during imagery capture
angular Angular or ‘attitude’ data about the orientation of the satellite during imagery capture
source File contains data on the imagery’s source such as who produced it and how.
lineage Details on the data’s lineage to delivery, who handled/processed the data, in what way, etc
platform Information on the satellite/platform that captured the imagery
bands Information on the spectral properties of each imaging band delivered
mapping Information on how to interpret the details in the data files.
Often a subset of platform or bands data.Common forms are:

  • gain and offset to apply to pixel values to get SI units
  • mapping pixel values to an enumeration of meaning
  • identifying the values a bit mask in each pixel correspond to
contours When used as structured data, the contours roles refers to the rational polynomial coefficients file, defining the coefficients of the imagery’s relative service

Example: [“metadata”, “structured”, “general”, “lineage”, “platform”, “bands”]

“license”

“license” is a special type, used exclusively for resources that provide either the license for data itself, or information about it.
The most common licenses are either text/plain or application/pdf files.

“custom”

“custom” is a special type, used exclusively for resources that are part of a custom order, for resources which do not fall into other established roles