Arlula API Documentation

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.



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 and long 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
    Define a bounding box as an area of interest by providing the north, south, east and west search parameters to the search request.
    All 4 parameters need to be provided for the bounding box to be valid.
At least one of these methods MUST be provided for the request to be valid.

Response Details

The /api/search endpoint returns a JSON encoded response consisting of a list of Search Result objects.
[
  { Search Result },
  { Search Result },
  ...
]
Each Search Result entry is a JSON object with the following structure:
{
  "supplier": "",
  "eula": "",
  "id": "",
  "sceneID": "",
  "date": "",
  "center": {
      "lat": 0,
      "long": 0
  },
  "bounding": [],
  "area": 0,
  "overlap": {
      "area": 0,
      "percent": 0,
      "polygon": []
  },
  "price": {
    "scene": {
      "base": 0,
      "seats": {
          "min": 0,
          "max": 0,
          "additional": 0
      }
    },
    "aoi": {
      "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 notation
area number area the imagery covers in square kilometers
overlap Overlap object overlap between the imagery and the interest area, only provided if searching by a bounding box, 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
These search results can be used to assess the available imagery for your query, and then, if suitable imagery is available, it can then be purchased via the Order New Endpoint.

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": 0,
  "polygon": []
}
field data type purpose
area number area in sq km of the overlap between search and result
percent number percent of the original search area this scene overlaps
polygon [][]number polygon of overlap area
Pricing Object
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.
Depending on your search criteria, two different prices may be available for your imagery.
The price object provides these details, as well as which options are available.
The price object has two fields:
- scene: which provides pricing for purchasing a whole image capture (what you see in the thumbnail image), or
- aoi: which is only available if searching by an area (much like the overlap object above), and provides pricing for only purchasing the imagery in your search area. This field may also be absent, indicating an inability to purchase only the AOI portion of this scene, for any of the following reasons:
 - the supplier does not support AOI ordering (such as landsat)
 - the portion of your AOI within this scene is less than the suppliers minimum order
 - the portion of your AOI within this scene fails supplier swath width requirements
The contents of the scene and aoi fields is a pricing object, which 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 each organisation that uses the image constitutes a seat. If you are distributing this image to other organisations, this will apply. Please consult the EULA for more information.
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 additional amount to be added to base for purchasing this imagery.
The applicable entry is one where the required number of seats is:
- greater than or equal to that entry's min value
- less than or equal to that entry's max value, or that entry's 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.

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": "",
  "trim": false,
  "seats": 1,
  "webhooks": [""],
  "emails": [""],
}

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
trim boolean if true, the order will process a request to only order your AOI rather than the whole scene. If true where AOI orders are unavailable, an error will be returned
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
The `trim` parameter is a powerful and important part of the order endpoint, and it controls both the balance changed to your account, and the imagery provided.
When `trim` is not present, or is false, the whole scene's imagery will be ordered and the price stipulated in the `price.scene` field of the search result will be charged.
When `trim` is true. Your account will be charged the amount stipulated in `price.aoi`; and the imagery ordered will be the intersection of the scene and your search area (defined in the `overlap` field of the search result).
Trim may only be true if the search result included a `price.aoi` value. If it does not, review the `annotations` field for the reason AOI ordering is not available for this result.

Webhooks and Emails
Your API can be notified of your order being complete by providing either a webhook or email address, to which the order details, and its resource list, will be provided when the order is complete.
Upon the order being completed a Detailed Order object (as returned by this and the Order Get endpoints) will be sent to the webhook as a POST request, or as a human readable email to the provided address.

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": "",
  "status": "",
  "total": 0,
  "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
status string current status of the order (see below for values)
total number total price of the order in US cents
resources array lists the resources available for download on the order (see below)
NOTE: the resources array will be ommitted if there are no resources available for the order yet.

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


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

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.


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": "",
  "status": "",
  "total": 0,
  "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
status string current status of the order (see below for values)
total number total price of the order in US cents
resources array lists the resources available for download on the order (see below)
NOTE: the resources array will be ommitted if there are no resources available for the order yet.

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


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.

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/vendor

Version 1.3.0:

Added signup procedure for non activated accounts

Version 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
Order object changes:
  • 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)