Orders API

The Orders API provides endpoints for retrieving details of past orders, tasking campaigns and datasets created through the Archive and Tasking APIs, viewing their status, and downloading the delivered file resources in a dataset.

The orders API consists of 3 core entity list endpoints:

  • List orders, which will list all orders your account has access to
  • List campaigns, which lists all current and past tasking campaigns your account has access to
  • List datasets, which list all archive datasets, and delivered tasking capture datasets your account has access to

And 3 sublist endpoints:

And 3 core entity get endpoints

  • Get order, which will list the details of an order on your account, including all its constituent tasking campaigns and datasets
  • Get campaign, which will list the details of a tasking campaign and any captures delivered and available as downloadable datasets
  • Get dataset, which will list the details of a dataset, whether an archive purchase or a capture from a tasking campaign, as well as all its constituent resource files for download.

And finally the 2 file resource endpoints:

  • Get resource, which retrieves the file resources details and description, such as its roles, format and checksum.
  • Download resource, which requests download of a resource associated with an order, such as the imagery or its metadata

List Order History

The List endpoint returns all pending and completed orders.

Example: /api/orders?page=2&size=25

Query Parameters

name data type purpose
page Number The index of the page in the list to be viewed (starting at 0)
size Number The size/length of the page (the number of items to be returned in a full page). Defaults of 20.

Response Details

The /api/orders endpoint returns a JSON encoded response consisting of a paginated list of Order objects.

Copy to Clipboard

Each Order entry is a JSON object with the following structure:

Copy to Clipboard

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

List Tasking Campaigns

The List endpoint returns all pending and completed orders.

Example: /api/campaigns?page=2&size=25

Query Parameters

name data type purpose
page Number The index of the page in the list to be viewed (starting at 0)
size Number The size/length of the page (the number of items to be returned in a full page). Defaults of 20.

Response Details

The /api/campaigns endpoint returns a JSON encoded response consisting of a paginated list of Tasking Campaign objects.

Copy to Clipboard

Each Tasking Campaign entry is a JSON object with the following structure:

Copy to Clipboard

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

List Datasets

The List endpoint returns all pending and available datasets.

Example: /api/datasets?page=2&size=25

Query Parameters

name data type purpose
page Number The index of the page in the list to be viewed (starting at 0)
size Number The size/length of the page (the number of items to be returned in a full page). Defaults of 20.

Response Details

The /api/datasets endpoint returns a JSON encoded response consisting of a paginated list of Dataset objects.

Copy to Clipboard

Each Dataset entry is a JSON object with the following structure:

Copy to Clipboard

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

List Order Campaigns

The List order campaigns endpoint allows the list of all tasking campaigns that are part of a given order to be retrieved

Example: /api/order/:id:/campaigns

Path Parameters

name purpose
id UUID identifying the order you wish to retrieve campaigns from

Response Details

The /api/order/:id:/campaigns endpoint returns a JSON encoded response consisting of a paginated list of Tasking Campaign objects, just as the campaign list endpoint does.

List Order Datasets

The List order datasets endpoint allows the list of all datasets that are part of a given order to be retrieved.

This will include all archive datasets ordered, as well as any datasets that are delivery of captures from a tasking campaign

Example: /api/order/:id:/datasets

Path Parameters

name purpose
id UUID identifying the order you wish to retrieve datasets from

Response Details

The /api/order/:id:/datasets endpoint returns a JSON encoded response consisting of a paginated list of Datasets objects, just as the dataset list endpoint does.

List Campaign Datasets

The List campaign datasets endpoint allows the list of all datasets that have been delivered as captures for a given tasking campaign.

Example: /api/campaign/:id:/datasets

Path Parameters

name purpose
id UUID identifying the tasking campaign you wish to retrieve datasets from

Response Details

The /api/campaign/:id:/datasets endpoint returns a JSON encoded response consisting of a paginated list of Datasets objects, just as the dataset list endpoint does.

Get Order

The Get Order endpoint allows the return of a specific order, including its constituent campaigns and datasets.

Example: /api/order/:id:

Query Parameters

name data type purpose
id string UUID identifying the order you wish to retrieve

Response Details

The /api/order/:id: endpoint returns a JSON encoded Order object, with the structure:

Copy to Clipboard

Response

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

NOTE: the campaigns and datasets arrays will be omitted if the order does not contain any of the respective entities.

Get Campaign

The Get Campaign endpoint allows the return of an individual tasking campaign, including any datasets making up its delivered captures..

Example: /api/campaign/:id:

Path Parameters

name data type purpose
id string UUID identifying the campaign you wish to retrieve

Response Details

The /api/campaign/:id: endpoint returns a JSON encoded Tasking Campaign object, with the structure:

Copy to Clipboard

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

NOTE: the datasets array will be omitted if the campaign has not yet made any captures.

Get Dataset

The Get Dataset endpoint allows the return of a specific dataset, including its constituent file resources that can be downloaded.

Example: /api/dataset/:id:

Path Parameters

name data type purpose
id string UUID identifying the dataset you wish to retrieve

Response Details

The /api/dataset/:id: endpoint returns a JSON encoded Dataset object, with the structure:

Copy to Clipboard

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

NOTE: the datasets array will be omitted if the dataset is not yet in the completed state..

Get Resource

The Get Resource endpoint returns a resource structure for review. The data available does not differ from that returned by a dataset get request, but can be used if an ID is the only detail available.

Example: /api/resource/:id:

Path Parameters

name data type purpose
id string UUID identifying the resource you wish to retrieve

Response Details

The /api/dataset/:id: endpoint returns a JSON encoded Resource object, with the structure:

Copy to Clipboard

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

Download Resource

The Download Order Resource endpoint facilitates the download of a resource’s contents.

Example: /api/resource/:id:/data

Path Parameters

name data type purpose
id string UUID identifying the resource you wish to download, found in the Resource Object on its respective dataset.

Response Details

The /api/resource/:id:/data endpoint will return a byte stream of the contents of the file you requested, or redirect to a path that will do so.
A 410 Gone HTTP status code will be returned if storage for this order has expired and the resources are no longer available, which is annotated on the parent dataset.

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)
status string current status of the order (see below for values)
total number The total price of the order in US cents
discount number The discount applied to the order by any order or user coupons
tax number The tax paid on the order

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.

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 cloud, cloud-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