Overview
The Arlula infrastructure is predominantly broken down into two resource types:
- Search, for obtaining a list of satellite imagery available for the request's search criteria
- Orders, for requesting purchase of imagery and its associated data that will be
delivered to
the provided contact. This is broken down into:
- New order, which creates a new order, and pays for purchasing imagery
- List orders, which will list all past and current orders on your account
- Get order, which will list the details and any associated resources of an order on your account
- Get resource, which requests download of a resource associated with an order, such as the imagery or its metadata
Authentication
Making requests to the Orders API requires providing API Auth credentials for every request as part of the request header.
To obtain API credentials, you will need to Sign Up and be issued with API Credentials.
All requests to the API must be made via a https connection
The authentication is achieved by providing your API Key and API Password using the HTTP Basic Auth Mechanism.
Testing
An endpoint is available at/api/test
that does nothing other than check your
authentication.
This is often useful if you want to check your setup prior to making actual requests.
Search
GET /api/archive/search
The Search endpoint provides facilities to search Arlula and its suppliers for satellite imagery.
Query parameters
name | data type | purpose |
---|---|---|
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 |
res | A positive number or label (see below) | desired resolution of imagery, all imagery will be of this resolution 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 |
supplier | string matching the "key" 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) |
off-nadir | number between 0 and 45 (default 45) | (optional) Only return imagery with the off nadir angle during capture less than the specified criteria |
Resolution Labels
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.
label | range |
---|---|
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 |
vlow | all results |
Interest Area
The API currently supports providing an interest area in 2 ways:- a point of interest
Define a point of interest by providing the
lat
andlong
search parameters to the search request.
Point of interest will take priority if a bounding box is also provided- a bounding box defining an area of interest
At least one of these methods MUST be provided for the request to be valid.Define a bounding box as an area of interest by providing thenorth
,south
,east
andwest
search parameters to the search request.
All 4 parameters need to be provided for the bounding box to be valid.Response Details
The/api/archive/search
endpoint returns a JSON encoded response consisting of a list of Search Result objects.
Each Search Result entry is a JSON object with the following structure:[ { Search Result }, { Search Result }, ... ]
{ "supplier": "landsat", "eula": "https://creativecommons.org/licenses/by/3.0/legalcode", "id": "eyJhb...AYTqwM", "sceneID": "LC08_L2SP_089084_20180103_20200902_02_T2_SR", "platform": "landsat-8", "date": "2018-01-03T23:44:15.251922Z", "center": { "long": 151.22751402682792, "lat": -34.39869019896421 }, "bounding": [ [150.6280867211815, -33.559442990585], [150.12420905764873, -35.27082587573161], ... ], "area": 36842.9803, "overlap": { "area": 12, "percent": { "scene": 100, "search": -1 }, "polygon": [ [150.6280867211815, -33.559442990585], [150.12420905764873, -35.27082587573161], ... ] }, "price": { "base": 0, "seats": null }, "fulfillmentTime": 0, "resolution": 15, "thumbnail": "https://example.com/thumbnail.jpeg", "cloud": 72.19, "offNadir": 0, "annotations": [] }
A full reference for the structure can be found in the reference section below
Order
POST /api/archive/order
The New Order endpoint allows a new order requesting imagery to be made.
Query Body
The body must be a JSON object with the following structure:{ "id": "", "eula": "", "seats": 1, "webhooks": [""], "emails": [""], "team": "", "coupon": "" }
Example body:{ "id":"eyJhb...AYTqwM", "eula":"https://creativecommons.org/licenses/by/3.0/legalcode", "seats":4, "webhooks":[ "https://example.com/webhook-a", "https://example.com/webhook-b" ], "emails":[ "email-a@example.com", "email-b@example.com" ] }
A full reference for the structure can be found in the reference section below
Response Details
The
/api/archive/order
endpoint returns a JSON encoded response consisting of a Orderobject, with a structure like the following structure:{ "id": "0e3...ab", "createdAt": "2021-02-25T03:40:16.00877Z", "updatedAt": "2021-02-25T03:40:18.157458Z", "supplier": "landsat", "imageryID": "eyJhb...AYTqwM", "sceneID": "LC08_L2SP_089084_20180103_20200902_02_T2_SR", "status": "complete", "total": 0, "type": "archive-aoi", "expiration": null, "resources": [ ... ] }
A full reference for the structure can be found in the reference section below
List
GET /api/order/list
The List endpoint returns all pending and completed orders.
The /api/order/list endpoint returns a JSON encoded response consisting of a list of Order objects.
Response Details
Each Order entry is a JSON object with the following structure:[ { Order }, { Order }, ... ]
{ "id": "0e3...ab", "createdAt": "2021-02-25T03:40:16.00877Z", "updatedAt": "2021-02-25T03:40:18.157458Z", "supplier": "landsat", "imageryID": "eyJhb...AYTqwM", "sceneID": "LC08_L2SP_089084_20180103_20200902_02_T2_SR", "status": "complete", "total": 0, "type": "archive-aoi", "expiration": null, }
A full reference for the structure can be found in the reference section below
Get Order
GET /api/order/get
The Get Order endpoint allows the return of a detailed order object, including a list of resources that are available for download.
Example: /api/order/get?id=123456789Query Parameters
name data type purpose id string UUID identifying the order you wish to retrieve Response Details
The /api/order/get endpoint returns a JSON encoded response consisting of a Detailed Order object, with the structure:{ "id": "0e3...ab", "createdAt": "2021-02-25T03:40:16.00877Z", "updatedAt": "2021-02-25T03:40:18.157458Z", "supplier": "landsat", "imageryID": "eyJhb...AYTqwM", "sceneID": "LC08_L2SP_089084_20180103_20200902_02_T2_SR", "status": "complete", "total": 0, "type": "archive-aoi", "expiration": null, "resources": [ { Resource }, { Resource }, ... ] }
ResponseA full reference for the order structure can be found in the reference section below
NOTE: the resources array will be omitted if there are no resources available for the order yet, or if the order is not yet complete.
Resource Object
Completed orders will have at least one resource available to download that provides the requested imagery and its associated metadata.
Each Resource is an object like the following:{ "id": "7de71ac7-245e-462e-b34f-af631538cac0", "createdAt": "2021-02-25T03:40:18.157458Z", "updatedAt": "2021-02-25T03:40:18.157458Z", "order": "0e3...ab", "name": "LC08_L2SP_089084_20180103_20200902_02_T2_SR_B4.TIF", "type": "img_tif", "format": "image/tiff; application=geotiff; profile=cloud-optimized", "roles": ["data", "raster", "reflectance", "red"], "size": 97096450, "checksum": "MD5:13400524ccc...b0d4faa5" }
A full reference for the resource structure can be found in the reference section below
Get Resource
GET /api/order/resource/get
The Get Order Resource endpoint allows the download of a resource contents.
Example: /api/order/resource/get?id=123456789Query Parameters
name data type purpose id string UUID identifying the resource you wish to retrieve, found in the Resource Object Response Details
The/api/order/resource/get
endpoint will return a byte stream of the contents of the file you requested, or redirect to a path that will do so.
A410 Gone
HTTP status code will be returned if storage for this order has expired and the resources are no longer available.Search Result
The/api/archive/search
endpoint returns a list of search result objects each result resembles the following:{ "supplier": "landsat", "eula": "https://creativecommons.org/licenses/by/3.0/legalcode", "id": "eyJhb...AYTqwM", "sceneID": "LC08_L2SP_089084_20180103_20200902_02_T2_SR", "platform": "landsat-8", "date": "2018-01-03T23:44:15.251922Z", "center": { "long": 151.22751402682792, "lat": -34.39869019896421 }, "bounding": [ [150.6280867211815, -33.559442990585], [150.12420905764873, -35.27082587573161], ... ], "area": 36842.9803, "overlap": { "area": 12, "percent": { "scene": 100, "search": -1 }, "polygon": [ [150.6280867211815, -33.559442990585], [150.12420905764873, -35.27082587573161], ... ] }, "price": { "base": 0, "seats": null }, "fulfillmentTime": 0, "resolution": 15, "thumbnail": "https://example.com/thumbnail.jpeg", "cloud": 72.19, "offNadir": 0, "annotations": [] }
Fields
field type purpose supplier string identifies the supplier of the imagery, used in ordering the imagery eula string eula that will be agreed to if ordering this image id string ordering ID for this scene and Area Of Interest, used to order the imagery sceneID string ID for the suppliers image capture, can be used to identify the same source imagery between searches 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 center lat int, long int center coordinates of the imagery bounding [][]number bounding polygon of the imagery in the geoJSON ([long, lat]) notation area number area the scene covers in square kilometers overlap Overlap object overlap between the imagery and the interest area, or an area constructed from it to meet minimum order requirements, see below price Pricing object Price to purchase the imagery, see details below fulfillmentTime number estimated time to fulfill an order of this imagery in hours, 0 is instant resolution number resolution of the imagery in meters per pixel 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 annotations string array annotates result with information, such as why AOI pricing is not available
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:{ "area": 12, "percent": { "scene": 100, "search": -1 }, "polygon": [ [150.6280867211815, -33.559442990585], [150.12420905764873, -35.27082587573161], ... ] }
field data type purpose 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
Pricing Object
Many suppliers require loading to licence additional seats to their imagery, as well as area based pricing for the size of the Area Of Interest (AOI), this object provides the details necessary for determining the final price of a scene.
Regardless of search criteria, we endeavor to provide a price for your area of interest rather than purchasing the whole scene.
To enable this, when your search by a point, or for less than a suppliers minimum order, we construct an area of interest that will meet this minimum order to provide the minimum price.
For this reason it is critically important that you review the polygon found inoverlap.polygon
of the search result. As this will be the polygon ordered from the supplier if they support AOI ordering.
All pricing is provided in US cents.
The contents of the pricing object follows a structure of:{ "base": 11500, "seats": [ { "min": 2, "max": 5, "additional": 2300 }, { "min": 6, "max": 0, "additional": 5200 } ] }
field data type purpose base number the base static price for the imagery, this is the portion the image will always cost seats array A list of details for the amount the price changes by for additional seats min number minimum number of seats to which this price range applies max number maximum number of seats to which this price range applies (0 represents no maximum) additional number the additional price to be paid in this range
Determining final price
All imagery will cost its base price, and purchases with additional seats may attract additional charges, described by this structure.
If the seats array is empty, no additional charge is applicable for any seat number.
If the seats array is populated, each object represents pricing for a range of seats, and the matching objects additional amount to be added to base for purchasing this imagery. Note: add only the matching seats cases additional amount, do not aggregate from lower seat counts.
The applicable entry is one where the required number of seats is: - greater than or equal to that entry's min value, and - less than or equal to that entries max value, or that entries max value is 0 (representing no upper bounds)
When purchasing the imagery, the amount charged to the requesting users account, will be base + additional for the appropriate seats entry.
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
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 insqkm overlap.polygon
ENLR: The intersection of your search area and this scene was less than the suppliers minimum order of
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 insqkm, the AOI was enlarged to meet the minimum order 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, Theoverlap.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, theoverlap.polygon
is likely to match the bounding polygon. Pricing provided is for the whole scene.Order Request
The/api/archive/order
endpoint requires a JSON object specifying the order details, which resembles the following:{ "id":"eyJhb...AYTqwM", "eula":"https://creativecommons.org/licenses/by/3.0/legalcode", "seats":4, "webhooks":[ "https://example.com/webhook-a", "https://example.com/webhook-b" ], "emails":[ "email-a@example.com", "email-b@example.com" ], "team": "0e3947...370ab", "coupon": "" }
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 seats number the number of seats being purchased for (affects pricing, see search documentation) 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 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).{ "event": "archive.order.complete", "timestamp": "", "payload: {} }
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.Order Object
The order object is a JSON object, that resembles:{ "id": "0e3...ab", "createdAt": "2021-02-25T03:40:16.00877Z", "updatedAt": "2021-02-25T03:40:18.157458Z", "supplier": "landsat", "imageryID": "eyJhb...AYTqwM", "sceneID": "LC08_L2SP_089084_20180103_20200902_02_T2_SR", "status": "complete", "total": 0, "type": "archive-aoi", "expiration": null, "resources": [ { Resource }, { Resource }, ... ] }
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 imageryID 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) 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 fulfill 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 aJSON 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:{ "id": "7de71ac7-245e-462e-b34f-af631538cac0", "createdAt": "2021-02-25T03:40:18.157458Z", "updatedAt": "2021-02-25T03:40:18.157458Z", "order": "0e3...ab", "name": "LC08_L2SP_089084_20180103_20200902_02_T2_SR_B4.TIF", "type": "img_tif", "format": "image/tiff; application=geotiff; profile=cloud-optimized", "roles": ["data", "raster", "reflectance", "red"], "size": 97096450, "checksum": "MD5:13400524ccc...b0d4faa5" }
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
, orapplication/json
(see roles reference for common examples)roles array of 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 eitherMD5
orSHA1
.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 resourceformat
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/pngCommon 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 newformat
androles
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 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 eitherMD5
ofSHA1
.
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 hierarchial tree describing the contents of a given resource
Roles should be read from start to end as being from least to most specific descriptor
Please review the tree of currently supported roles by expanding the relevant section below
"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
- "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
raster
, howevervector
andstructured
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 hierarchial.
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 themulti-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 asndvi
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 imageryorthorectified
for orthorectified imageryradiometrically-corrected
for imagery that has undergone radiometric correctionmosaic
for cases where a mosaic has been produced from multiple source images
["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
- "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"
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 thecloud
,cloud-shadow
andwater-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 ["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, oraoi
to identify the location boundary of the delivered Area Of Interest
["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 ofplatform
orbands
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["metadata", "structured", "general", "lineage", "platform", "bands"]
["metadata", "structured", "ephemeris", "angular"]
"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 eithertext/plain
orapplication/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 rolesChangelog
Version 1.0.0:
Initial version of API, supported:- search imagery
- order imagery
- orders list
- order get
- order
- resource get
Version 1.1.0:
Internal update for platform update:- added signature management internal api
- added admin pages to manage orders
Version 1.2.0:
Added SI Imaging as an imagery supplier/vendorVersion 1.3.0:
Added signup procedure for non activated accountsVersion 2.0.0:
AOI ordering for imagery
Search response structure changed:- added sceneID field
- added annotations
-
field - changed overlap to object with children:
- area
- percent
- polygon
-
Changed price field to include new field
aoi
which also contains pricing information for AOI order
- added trim field
Version 2.0.1:
Added new resource types:- `img_jp2` for JPEG Core 200 format imagery, and
- `meta_bundle` for aggregated or otherwise bundled metadata
Version 2.0.2:
Updated order status labels to clarify state ('manual' for awaiting supplier non-automated response caused confusion)Version 2.0.3:
Added additional resource types for scene geometry:- geo_json for geometry defined in the geoJSON standard
- geo_kml for geometry defined in Keyhole Markup Language (KML)
- geo_shp for bundled shapefiles and their metadata (zip file containing shp, shx, dbf and prj files)
- geo_bundle for geometry of a unknown or miscellaneous format provided by the supplier
Version 2020-12:
- Change in version number format (2020-12 rather than 3.0.0.
- Coordinates in a point are reversed order to be [long, lat] to be consistent with geoJSON and similar formats as an X, Y format.
- API account delete functionality.
- Webhook events now have a wrapper to their payload to support future planned usage
- MOQ ordering; all searches return an AOI price, increased to the supplier
minimum order if it was less than it. This causes several dependent changes:
- overlap field is always included and includes the polygon that will be ordered
- overlap.percent is now an object with two fields search and scene
- price is now a single pricing object that provides the AOI price, scene pricing is no longer provided
- remove trim as an ordering parameter
Version 2021-01
- Added additional server behaviors to enable UI's binding against the API (internal, version bump for bug tracking)
Version 2021-03
- Supplier search filter support
- Change to ordering ID encoding standard to support future planed features
Version 2021-09
- Added cloud cover archive search filter
- Added off nadir archive search filter
- Added ofFNadir to archive search results
- Added platform to archive search results
- Updated resource structure, adding roles, format, size and checksum fields
- a bounding box defining an area of interest