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

{
  "results": [
    {
      "polygon": [
        [
          [
            151.00074930000005,
            -33.727445099999954
          ],
          ...
          [
            151.00074930000005,
            -33.727445099999954
          ]
        ]
      ],
      "startDate": "2023-08-07T03:13:20.736Z",
      "endDate": "2023-09-07T03:13:20.736Z",
      "metrics": {
        "windowsAvailable": 0,
        "windowsRequired": 0,
        "orderArea": 0,
        "moq": 0
    },
      "gsd": 1.2,
      "supplier": "landsat",
      "orderingID": "eyJhb...AYTqwM",
      "offNadir": 21.5,
      "bands": [{
        "name": "Red",
        "id": "R",
        "min": 640,
        "max": 670
      }],
      "bundles": [{
        "key": "L1B",
        "bands": ["R"],
        "price": 0
      }],
      "licenses": [{
        "name": "CC BY 3.0",
        "href": "https://creativecommons.org/licenses/by/3.0/legalcode",
        "loadingPercent": 0,
        "loadingAmount": 0
      }],
      "priorities": [{
        "key": "high",
        "name": "High Priority",
        "description": "Description of priority level",
        "loadingPercent": 100,
        "loadingAmount": 0
      }],
      "cloud": [{
        "name": "Standard",
        "max": 30,
        "description": "Description of cloud level offering",
        "loadingPercent": 10,
        "loadingAmount": 0
      }],
      "platforms": [
        "landsat-8",
        "landsat-9"
      ],
      "annotations": [
        "string"
      ]
    }
  ],
  "failures": [{
    "type": "insufficient-los",
    "message": "Platforms will not have an overpass that meets search criteria in the date range given",
    "supplier": "example",
    "platforms": ["a", "b"],
    "details": {}
  }]
}

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

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 an Order object, containing the ordered tasking campaign.

This has a structure of:

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 and emails will be appended to any specified on the individual orders,
team will be set on any orders where a team is 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 Order object, containing the list of ordered tasking campaigns.

This will have 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

{
  "results": [
    {
      "polygon": [
        [
          [
            151.00074930000005,
            -33.727445099999954
          ],
          ...
          [
            151.00074930000005,
            -33.727445099999954
          ]
        ]
      ],
      "startDate": "2023-08-07T03:13:20.736Z",
      "endDate": "2023-09-07T03:13:20.736Z",
      "metrics": {
        "windowsAvailable": 0,
        "windowsRequired": 0,
        "orderArea": 0,
        "moq": 0
    },
      "gsd": 1.2,
      "supplier": "landsat",
      "orderingID": "eyJhb...AYTqwM",
      "offNadir": 21.5,
      "bands": [{
        "name": "Red",
        "id": "R",
        "min": 640,
        "max": 670
      }],
      "bundles": [{
        "key": "L1B",
        "bands": ["R"],
        "price": 0
      }],
      "licenses": [{
        "name": "CC BY 3.0",
        "href": "https://creativecommons.org/licenses/by/3.0/legalcode",
        "loadingPercent": 0,
        "loadingAmount": 0
      }],
      "priorities": [{
        "key": "high",
        "name": "High Priority",
        "description": "Description of priority level",
        "loadingPercent": 100,
        "loadingAmount": 0
      }],
      "cloud": [{
        "name": "Standard",
        "max": 30,
        "description": "Description of cloud level offering",
        "loadingPercent": 10,
        "loadingAmount": 0
      }],
      "platforms": [
        "landsat-8",
        "landsat-9"
      ],
      "annotations": [
        "string"
      ]
    }
  ],
  "failures": [{
    "type": "insufficient-los",
    "message": "Platforms will not have an overpass that meets search criteria in the date range given",
    "supplier": "example",
    "platforms": ["a", "b"],
    "details": {}
  }]
}

Result Metrics

Name	Data type	Purpose
windowsAvailable	Number	The number of capture passes available in the requested period.
windowsRequired	Number	The number of capture passes required to capture the target aoi.
orderArea	Number, square kilometers	The estimated deliverable scene size.
moq	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.
failures	[]Failure	Details reasons why suppliers could not fulfil the requested tasking.

Tasking Search Result

Name	Data type	Purpose
polygons	3d floating point array	Polygon representing the area to be ordered from the supplier, inflated to meet any supplier minimum order requirements as a valid order.
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.
metrics	Metrics object	Container for metrics about the request such as the number of captures needed for coverage and the total area to be ordered
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
priorities	[]Priority Level object	Options for order priority relevant to your order. Only those available for your order criteria will be presented.
cloud	[]Cloud coverage object	Requirement options the supplier provides, guaranteeing capture of a cloud coverage of this percentage or less. Options vary by supplier, and lower guarantees may reduce the likelihood of capture being successful in the required period.
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)

Failure

Name	Data type	Purpose
type	string	The type of failure reported by the supplier
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

Priority Level Object

Name	Data type	Purpose
key	string	The priority key that is to be provided to the order endpoint to purchase the bundle at this priority
name	string	A human readable name to refer to this priority level
description	string	A brief description of this priority level and any additional considerations it provides.
loadingPercent	number	The percentage loading this priority applies to the bundle’s price
loadingAmount	number	The static amount (in US cents) this priority adds to the bundle’s price

Cloud Coverage Object

Name	Data type	Purpose
max	number	The maximum cloud cover a capture may have to be considered successful if ordered under this coverage level
name	string	A human readable name to refer to this cloud coverage level
description	string	A brief description of this coverage level and any additional considerations it provides.
loadingPercent	number	The percentage loading this coverage level applies to the bundle’s price
loadingAmount	number	The static amount (in US cents) this coverage level adds to the bundle’s price

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

Tasking Campaign Object

Tasking orders are represented as a campaign for capture, called a Tasking Campaign.

The campaign persists details of the requested coverage and capture conditions, and will present details of the campaign’s status, and the datasets created from each capture in the campaign, representing delivered data.

Campaigns take the structure of:

Copy to Clipboard

Parameters

name	data type	purpose
id	string	UUID to uniquely identify the campaign
createdAt	string	datetime the campaign was created at (UTC timezone)
updatedAt	string	datetime of the last update to the campaign (UTC timezone)
status	string	current status of the campaign
orderingID	string	ID used to order the imagery
bundle	string	Key of the bundle ordered for this tasking campaign
license	string	License this tasking campaign was ordered under
priority	string	Priority code this campaign was ordered under
total	number	total price of the campaign in US cents
discount	number	Amount in US cents discounted from this campaign by coupon usage
tax	number	Tax collected on this tasking campaign in US cents
refunded	number	Amount in US cents refunded on this campaign.
order	string	UUID of the order the campaign belongs to
site	string\|null	UUID of the saved site the campaign is of (or null)
start	string	Datetime at which this capture campaign is to begin capture
end	string	Datetime that this campaign will be considered complete
aoi	3d float array	he polygon defining the Area Of Interest that this campaign is targeting
cloud	number	The maximum allowable cloud cover for captures in this campaign
gsd	number	Ground sample distance requirement for captures in this campaign
offNadir	number	The maximum allowable off nadir angle for captures in this campaign
supplier	string	The supplier fulfilling this campaign
platforms	string array	The list of acceptable capture platforms for this campaign
datasets	dataset array	The list of delivered datasets captured as part of this campaign

NOTE: the datasets array will be omitted if there are no datasets available for the campaign yet.