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:
The Search endpoint allows the searching of Arlula and its suppliers for satellite catalogue of archival imagery.
Search has historically been a GET request, with query parameters for the conditions, for example:/api/archive/search?start=2019-01-03&end=2019-04-13&res=low&lat=-33.8523&long=151.2108
This is maintained for backwards compatibility.
However, some search conditions such as polygon searches can cause this to exceed the maximum URL size. To resolve this, using a POST request is now the recommended way to place search requests, with conditions specified in a JSON body using the same keys for each property.
|start||date in YYYY-MM-DD||date of interest, or start of an interest period|
|end||date in YYYY-MM-DD||(optional) end of an interest period|
|gsd||A positive number or label (see below)||desired ground sample distance of imagery, all imagery will be of this GSD or better|
|lat||number between -90 and 90 inclusive||(optional) latitude of the point of interest for which imagery is requested|
|long||number between -180 and 180 inclusive||(optional) longitude of the point of interest for which imagery is requested|
|north||number between -90 and 90 inclusive||(optional) northern boundary of an interest area for which imagery is requested|
|south||number between -90 and 90 inclusive||(optional) southern boundary of an interest area for which imagery is requested|
|east||number between -180 and 180 inclusive||(optional) eastern boundary of an interest area for which imagery is requested|
|west||number between -180 and 180 inclusive||(optional) western boundary of an interest area for which imagery is requested|
|polygon||JSON array or WKT polygon string||(optional) polygon demarking an interest area for which imagery is requested.
NOTE: as a query parameter, WKT should be used, as a body JSON property, this must be in a coordinate array form (number)
|supplier||string matching the “supplier” property of search results||(optional) restrict results to only the given supplier|
|cloud||number between 0 and 100 (default 100)||(optional) Only return imagery with average total cloud percentage less than the specified criteria (note: scenes with more cloud may be clear over your Area Of Interest, use carefully)|
|offNadir||number between 0 and 45 (default 45)||(optional) Only return imagery with the off nadir angle during capture less than the specified criteria|
|offNadir||number between 0 and 45 (default 45)||(optional) Only return imagery with the off nadir angle during capture less than the specified criteria|
|sort||A Sorting descripting (see below)||(optional) the desired field to sort results by, and if that sort should be ascending or descending|
The resolution parameter may normally take a number as its input. However, in many cases a specifically defined resolution limit isn’t necessary.
For these cases, you can instead use a label that identifies a common resolution.
|very high||0.5m/pixel or better|
|vhigh||0.5m/pixel or better|
|high||1m/pixel or better|
|medium||5m/pixel or better|
|med||5m/pixel or better|
|low||20m/pixel or better|
|very low||all 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,
|field||string||The field to sort by|
|ascending||boolean||Whether the sort should be ascending or descending in order|
The supported fieldnames are:
The API currently supports providing an interest area in 3 ways:
- a point of interest
Define a point of interest by providing the
longsearch parameters to the search request.
- a bounding box defining an area of interest
Define a bounding box as an area of interest by providing the
westsearch parameters to the search request.
All 4 parameters need to be provided for the bounding box to be valid.
- a polygon defining an area of interest
Define a polygon as an area of interest by providing the
polygonsearch parameter to the search request.
A polygon may be provided either as JSON array notation, i.e.
as Well Known Text (WKT) geometry representation, i.e.
POLYGON ((0 0,0 1,1 1,1 0,0 0)).
In both cases the geometry must be appropriately escaped for URL encoding and must be a closed loop polygon.
At least one of these methods MUST be provided for the request to be valid.
All coordinates must also be specified in latitude and longitude, not projected coordinates.
/api/archive/search endpoint returns a JSON encoded response as a SearchResponse Object with a structure of.
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:
/api/archive/order endpoint returns a JSON encoded response consisting of a Order object, with a structure like the following structure:
Archive Batch Order
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 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
/api/archive/order/batch endpoint returns a JSON encoded response consisting of an array of Order objects, with the following structure:
A full reference for the order object’s structure can be found in the reference section below
/api/archive/search endpoint returns a list of search result objects each result resembles the following:
|sceneID||string||ID for the suppliers image capture, can be used to identify the same source imagery between searches|
|supplier||string||identifies the supplier of the imagery, used in ordering the imagery|
|platform||string||The platform which captured the imagery, generally identifies the constellation, or specific satellite that captured the imagery.|
|date||datetime||date the imagery was captured|
|thumbnail||string||URL of a low resolution JPEG thumbnail of the imagery that will be provided|
|cloud||number||estimated percentage of the imagery that is cloud cover|
|offNadir||number||The degrees away from Nadir (straight down) the satellite was oriented during capture|
|gsd||number||spatial resolution of the imagery in meters per pixel|
|bands||Band object||List of the Spectral Bands captured in this scene, see below|
|area||number||area the scene covers in square kilometers|
|center||lat int, long int||center coordinates of the imagery|
|bounding||number||bounding polygon of the imagery in the geoJSON ([long, lat]) notation|
|overlap||Overlap object||overlap between the imagery and the interest area, or an area constructed from it to meet minimum order requirements, see below|
|fulfillmentTime||number||estimated time to fulfill an order of this imagery in hours, 0 is instant|
|orderingID||string||ordering ID for this scene and Area Of Interest, used to order the imagery|
|bundles||Bundle Option object||ordering bundles representing the available ways to order the imagery, see below|
|licenses||License object||License options this imagery may be purchased under, and the terms and pricing that apply, see below|
|annotations||string array||annotates result with information, such as what modifications were made to your search to make a valid order|
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:
|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)|
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
|area||number||area in sq km of the overlap between search and result|
|percent (scene)||number||percent of the whole scene the polygon represents|
|percent (search)||number||percent of the original search area (if bounding box) the AOI represents. This will be -1 for a point search, and may be greater than 100% if the original search is less than the suppliers minimum order|
|polygon||number||polygon of overlap area. This polygon is what will be ordered if the supplier supports ordering an area of interest|
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:
|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),
if the list is empty, all bands are provided.
|price||number||The base price for this bundle in US cents|
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:
|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|
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
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.
2. get the license’s “loadingPercent” value and make the following multiplication
price = bundlePrice * (1 + (loadingPercent/100))
3. get the license’s “loadingAmount” value and add it to the price
price = price + loadingAmount
4. round the value up to the nearest dollar (nearest hundred)
finalPrice = ceil(price/100)*100
You now have the final price of your scene in US cents
/api/archive/order endpoint requires a JSON object specifying the order details, which resembles the following:
|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 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.
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.
|location||string uri||a S3 URI to deliver the data to, upon order completion (note, the bucket must have role based authentication allowing
|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.|
The order object is a JSON object, that resembles:
|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, 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.
The order, once created may return several different status codes to indicate its current state of completion.
|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|
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
Completed orders will have at least one resource available to download that provides the requested imagery.
Each Resource has structure like the following:
|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
(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
Imagery and it’s metadata can be delivered in a variety of file formats, with the specific choice of format often varying with supplier.
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):
|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.
|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.|
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
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
roles fields instead (see below).
The returned legacy types are
|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
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.
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:
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
- “raster” resources are traditional pixel images
- “vector” resources are geographic features like points, polygons and features
- “structured” resources are information in machine readable data formats like JSON
At this time, primary data is only returned with the
structured are reserved for future use.
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 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
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:
pansharpenedfor pansharpened imagery
orthorectifiedfor orthorectified imagery
radiometrically-correctedfor imagery that has undergone radiometric correction
mosaicfor cases where a mosaic has been produced from multiple source images
Example: [“data”, “raster”, “reflectance”, “multi-band”, “red”, “green”, “blue”, “nir”, “pansharpened”]
Thermal reflectance data from a thermal sensor like landsat-8’s TIRS sensor.
Example: [“data”, “raster”, “temperature”]
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”]
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”]
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.
Not supported at this time, but reserved for future use
Descriptive metadata that provides information about the primary data.
Metadata generally comes in 3 types
- “raster” resources are traditional pixel images, describing a value at each pixel location
- “vector” resources are geographic features such as the polygon within which is valid data, or where the seams of adjacent tiles are
- “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 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
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
|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 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 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:
scenein which case it is the boundary for the whole source scene of the imagery, or
aoito identify the location boundary of the delivered Area Of Interest
Example: [“metadata”, “vector”, “reference”, “aoi”]
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 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.
|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
|contours||When used as structured data, the contours roles refers to the
Example: [“metadata”, “structured”, “general”, “lineage”, “platform”, “bands”]
“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
“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