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, with a minimum of TLS1.1 as the cypher.
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.The Documentation
Search
GET /api/search
The Search endpoint provides facilities to search Arlula and its suppliers for satellite imagery.
Example:
/api/search?start=2019-01-03&end=2019-04-13&res=low&lat=-33.8523&long=151.2108
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, imagery of this resolution or greater will be returned |
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 |
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 range.
label | range |
---|---|
very high | <0.5m |
vhigh | <0.5m |
high | 0.5m-1m |
medium | 1m-5m | med | 1m-5m |
low | 5m-20m |
very low | >20m |
vlow | >20m |
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/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": "", "eula": "", "id": "", "sceneID": "", "date": "", "center": { "lat": 0, "long": 0 }, "bounding": [], "area": 0, "overlap": { "area": 0, "percent": { "scene": 0, "search": 0 }, "polygon": [] }, "price": { "base": 0, "seats": { "min": 0, "max": 0, "additional": 0 } }, "fulfillment": 0, "resolution": 0, "thumbnail": "", "cloud": 0, "annotations": [] }
Response parameters
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 unique ID for the imagery, used to order the imagery sceneID string ID for the suppliers image capture, can be used to identify the same source imagery between searches res A positive number or label (see below) desired resolution of imagery, imagery of this resolution or greater will be returned 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 imagery 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 fulfillment number estimated time to fulfill a request in order to order 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 annotations string array annotates result with information, such as why AOI pricing is not available
Overlap Object
Overlap details are only provided if searching by a bounding box (or polygon in the future), it will be absent if searching by a point. The Overlap object has the following structure:{ "area": 0, "percent": { "scene": 0, "search": 0 }, "polygon": [] }
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, 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
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 iscritically important that you review the polygon found in overlap.polygon. As this will be the polygon ordered from the supplier if they support AOI ordering.
Many suppliers require different licencing or pricing to licence additional seats to the imagery, as well as allowing purchase of whole scenes, or just the Area Of Interest (AOI), this object provides details for the different pricing options.
All pricing is provided in US cents.
The contents of the pricing object has the following structure:{ "base": 0, "seats": [ { "min": 0, "max": 0, "additional": 0 } ] }
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
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 charges to the requesting users account, will be base + additional for the appropriate seats entry. Where the appropriate pricing object is selected by your order request (see order endpoint documentation).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. - a bounding box defining an area of interest
Order
POST /api/order/new
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": [""],
}
Example body:
{ "id":"123456789", "eula":"...", "seats":4, "webhooks":[ "webhook-a", "webhook-b" ], "emails":[ "email-a", "email-b" ], }
Query 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 | 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 | a list of email addresses (strings) that the order details will be sent to once the order is complete and ready for collection |
Ordering Scenes or Areas of Interest
From version2020-12
and onwards, the pricing provided by a search result is always for the searched Area Of Interest, or a minimum order containing it.
Ordering the search ID will always order a trimmed scene if it is smaller than the scene and the supplier supports AOI ordering (see search result annotations).
As a result the
trim
parameter of the order request from prior versions is now depreciated and will be ignored if included in requests.
Integrators are encouraged to remove the trim
parameter to avoid any future conflicts or revised requirements.
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 will be sent to the provided address with an event wrapper with the structure of
{
"event": "archive.order.complete",
"timestamp": "",
"payload: {}
}
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 order 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.
Response Details
The /api/order/new endpoint returns a JSON encoded response consisting of a Detailed Order object, with the structure:{
"id": "",
"createdAt": "",
"updatedAt": "",
"supplier": "",
"imageryID": "",
"sceneID": "",
"status": "",
"total": 0,
"type": "",
"expiration": null,
"resources": [
{ Resource },
{ Resource },
...
]
}
Response 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) |
Resource Object
Completed orders will have at least one resource available to download that provides the requested imagery.Each Resource has the following structure:
{
"id": "",
"createdAt": "",
"updatedAt": "",
"order": "",
"name": "",
"type": ""
}
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 | type of resource (see below) |
Resource Types
There are several types of resources that may be returned by suppliers.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)
Order expiration
Orders, once complete are retained in storage for 1 month from completion/delivery. After this date the orders resources are no longer available for delivery/retrieval from the user interface or order/resource/get endpoint.The expiration field of an order identifies the date and time after which resources will not be retrievable. The field will be a
JSON null
under the following conditions:
- The order is not yet complete, expiration will start once the order is complete
- The order is from a public dataset such as the landsat or sentinel missions and will not expire
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 |
List
GET /api/order/list
The List endpoint returns all pending and completed orders.
Response Details
The /api/order/list endpoint returns a JSON encoded response consisting of a list of Order
objects.
[
{ Order },
{ Order },
...
]
Each Order entry is a JSON object with the following structure:
{
"id": "",
"supplier": "",
"imageryID": "",
"status": "",
"total": 0,
"sceneID": "",
"type": "",
"expiration": null
}
Response Parameters
name | data type | purpose |
---|---|---|
id | string | UUID to uniquely identify the order |
supplier | string | supplier providing the imagery |
imageryID | string | ID used to order the imagery |
status | string | current status of the order (see Order for values) |
total | number | total price of the order in US cents |
sceneID | string | suppliers scene ID to identify the order |
type | string | order type designation (archive, custom, event orders; scene v aoi orders) |
expiration | nullable string | timestamp for order expiration (see below for details) |
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=123456789
Query 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": "",
"createdAt": "",
"updatedAt": "",
"supplier": "",
"imageryID": "",
"sceneID": "",
"status": "",
"total": 0,
"type": "",
"expiration": null,
"resources": [
{ Resource },
{ Resource },
...
]
}
Response 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 | ID for the suppliers image capture, can be used to identify the same source imagery between searches |
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) |
Resource Object
Completed orders will have at least one resource available to download that provides the requested imagery.Each Resource has the following structure:
{
"id": "",
"createdAt": "",
"updatedAt": "",
"order": "",
"name": "",
"type": ""
}
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 | type of resource (see below) |
Resource Types
There are several types of resources that may be returned by suppliers.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)
Order expiration
Orders, once complete are retained in storage for 1 month from completion/delivery. After this date the orders resources are no longer available for delivery/retrieval from the user interface or order/resource/get endpoint.The expiration field of an order identifies the date and time after which resources will not be retrievable. The field will be a
JSON null
under the following conditions:
- The order is not yet complete, expiration will start once the order is complete
- The order is from a public dataset such as the landsat or sentinel missions and will not expire
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 |
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=123456789
Query 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.A
410 Gone
HTTP status code will be returned if storage for this order has expired
Changelog
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 imagerySearch 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