Archive API

The Archive API provides a series of endpoints with which to query and order archival satellite imagery (captured in the past).

The Archive API consists of 3 endpoints:

• Search, for obtaining a list of satellite imagery available for the requested search criteria
• New order, which creates a new order, and pays for purchasing a single dataset, or
• Batch Order, for ordering multiple dataset in a single operation

Archive Search

Body/Query parameters

Where the response will contain either a list of string error messages encountered processing your request, or a list of Search Result objects that are your search results.

Each Search Result entry is a JSON object with the following structure:

Archive Order

Response Details

The /api/archive/order endpoint returns a JSON encoded response consisting of an Order object, containing the ordered archive dataset. This has a structure of:

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

Archive Batch Order

Response Details

The /api/archive/order/batch endpoint returns a JSON encoded response consisting of an Order object, containing all ordered archive datasets:

This has a structure of:

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

Search Result

The /api/archive/search endpoint returns a list of search result objects each result resembles the following:

Band Object

Each satellite sensor captures imagery in a series of “bands” which correspond to a portion of the electromagnetic spectrum. The common “visible” wavelengths such as red, green and blue are common, but other regions, such as near infrared and short wave infrared are also available. The exact range for these bands does differ between satellites however, as a result we present the details on the available bands for review, to ensure the imagery meets your needs.

The Band object has the following structure:

Overlap Object

Each search result has an overlap object identifying how the search area intersects with the scene, and what area will be ordered with the results id

The Overlap object has the following structure

Bundle Object

Many suppliers offer imagery at different levels of processing to suit different purposes, and others allow ordering of a subset of the bands that make up the capture (i.e. only get visual spectrum and ignore infrared). The Bundle object is how each of these ordering options is presented for selection.

The Bundle object has the following structure:

License Object

Many suppliers restrict the use case of imagery into several tiers of license, each entitling/allowing different levels of access or use of the imagery, frequently having different pricing according to this.

The License object has the following structure:

Annotations

The annotations field is there to inform you of any issues processing your request for the given scene. It includes non fatal errors and information on how they were handled which may affect your ordering of the imagery.

Annotations only appear for a handful of notable cases. To this end, all annotations begin with a 4 letter message code, followed by a colon “:” and a space before a human readable message.

The currently returned annotations are:

PONT: Your Point search was enlarged to an area centered on your search to meet the suppliers Minimum Order Quantity of sqkm

Returned when a point search was performed, to explain where the overlap area and polygon came from. The imagery ordered will be the polygon found in overlap.polygon

ENLR: The intersection of your search area and this scene was less than the suppliers minimum order of sqkm, the AOI was enlarged to meet the minimum order

Returned when an AOI is inflated to meet the minimum order, or the intersection of a search area and the scene must be inflated to meet the minimum order. The imagery ordered will be the polygon found in overlap.polygon which may differ from the provided search area, but will always include the portion of the image that is/is part of the AOI.

NAOI: This supplier does not support AOI imagery ordering

This supplier does not support Area Of Interest orders, The overlap.polygon is informative about the search with regard to the scene. Any pricing provided is for the scene as a whole which is what will be provided when ordering this scene.

COVR: Your AOI covers this whole scene. Pricing is for the whole scene

The provided Area Of Interest covers the whole scene, the overlap.polygon is likely to match the bounding polygon. Pricing provided is for the whole scene.

Calculating final price

Once you’ve selected your scene, the ordering bundle and license you wish to order follow this procedure to determine the final price you’ll be charged.

You now have the final price of your scene in US cents

Order Request

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

Object Parameters

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 archive order endpoint itself will only receive "archive.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.

Dataset Object

The dataset object is a JSON object, that resembles:

Dataset Parameters

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

Order Object

The order object is a JSON object, that resembles:

Order Parameters

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:

Resource Fields

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):

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

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

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.

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