Archive API

Home /
Arlula APIs /
Archive API

Order Archive Imagery

The New Archive Order endpoint lodges a new archive imagery order with the supplier providing the imagery requested.

post /api/archive/order

Request Body:

Field	Type	Description
bundleKey	string	The key of the bundle/order level you wish to purchase from the scene.
coupon	string	String coupon code to apply to discount the order pricing.
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.
eula	string	The End User License Agreement (EULA) href provided in the search results to confirm acceptance.
id	string	Unique ordering ID of the imagery to purchase, provided in the relevant search endpoint.
payment	string	The ID of the billing account to charge (if a paid order).
team	string	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).
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.

{
  "bundleKey": "8-band",
  "coupon": "",
  "emails": [
    "me@example.com"
  ],
  "eula": "https://creativecommons.org/licenses/by/3.0/legalcode",
  "id": "eyJhb...AYTqwM",
  "payment": "7de32061-dfeb-0232-b06e-af9090be6149",
  "team": "2e3c98e4-d19c-0097-921b-16d3ba4e7d31",
  "webhooks": [
    "http://example.com/order-callback"
  ]
}

Responses:

Successfully Placed Order

No Example for Response Code: 200

Occurs when your order has been received and accepted, however it is awaiting your manager’s approval.

No Example for Response Code: 202

Occurs when your request is malformed.

No Example for Response Code: 400

Occurs when basic authentication details are missing or invalid.

No Example for Response Code: 401

Occurs when you have not specified a payment method or there is no default one configured on your account and you have ordered a commercial paid image.

No Example for Response Code: 402

Occurs when your order failed due to certain constraints applied to your account.

No Example for Response Code: 403

Occurs when you are using an unactivated API Account for an order that requires payment. Please visit the dashboard page for this API Account and activate it.

No Example for Response Code: 412

Occurs when an error ocurred with one or more orders placed after you were billed, while processing the order request with the supplier. Please contact support.

No Example for Response Code: 422

Batch Order Archive Imagery

The New Archive Order Batch endpoint allows multiple orders requesting imagery to be made at the same time.

post /api/archive/order/batch

Request Body:

Field	Type	Description
coupon	string	String coupon code to apply to discount the order pricing.
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.
orders	array
payment	string	The ID of the billing account to charge (if a paid order).
team	string	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).
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.

{
  "coupon": "",
  "emails": [
    "me@example.com"
  ],
  "orders": [
    {
      "bundleKey": "8-band",
      "eula": "https://creativecommons.org/licenses/by/3.0/legalcode",
      "id": "eyJhb...AYTqwM"
    },
    {
      "bundleKey": "4-band",
      "eula": "https://creativecommons.org/licenses/by/3.0/legalcode",
      "id": "eyJhb...AYTqwM"
    }
  ],
  "payment": "7de32061-dfeb-0232-b06e-af9090be6149",
  "team": "2e3c98e4-d19c-0097-921b-16d3ba4e7d31",
  "webhooks": [
    "http://example.com/order-callback"
  ]
}

Responses:

Successfully Placed Order

No Example for Response Code: 200

Occurs when your order has been received and accepted, however it is awaiting your manager’s approval.

No Example for Response Code: 202

Occurs when your request is malformed.

No Example for Response Code: 400

Occurs when basic authentication details are missing or invalid.

No Example for Response Code: 401

Occurs when you have not specified a payment method or there is no default one configured on your account and you have ordered a commercial paid image.

No Example for Response Code: 402

Occurs when your order failed due to certain constraints applied to your account.

No Example for Response Code: 403

Occurs when you are using an unactivated API Account for an order that requires payment. Please visit the dashboard page for this API Account and activate it.

No Example for Response Code: 412

Occurs when an error ocurred with one or more orders placed after you were billed, while processing the order request with the supplier. Please contact support.

No Example for Response Code: 422

Retrieve Archive Scene

The Archive Scene Get endpoint provides facilities to retrieve a previously returned search result from a supplier.

get /api/archive/scene

URL Parameters:

* Required

Field	Description
id*	Ordering ID of the scene you wish to retrieve.


?id=eyJhb...AYTqwM

Responses:

The archive search result object describes a single capture and AOI pair that can be ordered with the provided details, and selecting the appropriate bundle and license.

No Example for Response Code: 200

Occurs when your request is malformed.

No Example for Response Code: 400

Occurs when basic authentication details are missing or invalid.

No Example for Response Code: 401

The Archive Scene Post endpoint provides facilities to retrieve a previously returned search result from a supplier.

post /api/archive/scene

Request Body:

Field	Type	Description
id	string	Ordering ID of the scene you wish to retrieve.

No Example for request body

Responses:

The archive search result object describes a single capture and AOI pair that can be ordered with the provided details, and selecting the appropriate bundle and license.

No Example for Response Code: 200

Occurs when your request is malformed.

No Example for Response Code: 400

Occurs when basic authentication details are missing or invalid.

No Example for Response Code: 401

Search Archive Imagery

The Archive Search endpoint provides facilities to search Arlula and its suppliers for satellite imagery. Start date and one of [lat, long], [north, south, east, west], or a polygon is required. It is highly recommended to use the POST /api/archive/search request when searching with a polygon, due to limitations on URL lengths.

get /api/archive/search

URL Parameters:

* Required

Field	Description
start*	Date of interest, or start of an interest period.
end	Optional end of an interest period. Must occur after `start` if provided.
gsd*	Desired ground sample distance of imagery, all imagery will be of this GSD or better.
lat	Latitude of the Point of Interest (POI). Also requires long. Mutually exclusive with [north, south, east, west] and polygon.
long	Longitude of Point of Interest (POI). Also requires lat. Mutually exclusive with [north, south, east, west] and polygon.
north	Northernmost point of Area of Interest (AOI). Also requires [south, east, west]. Mutually exclusive with [lat, long] and polygon.
south	Southernmost point of Area of Interest (AOI). Also requires [north, east, west]. Mutually exclusive with [lat, long] and polygon.
east	Easternmost point of Area of Interest (AOI). Also requires [north, south, west]. Mutually exclusive with [lat, long] and polygon.
west	Westernmost point of Area of Interest (AOI). Also requires [north, south, east]. Mutually exclusive with [lat, long] and polygon.
cloud	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). Default 100.
off-nadir	Only return imagery with the off nadir angle during capture less than the specified criteria. Default 45
polygon	A WKT string or json-encoded 3D array of points in long, lat format. Cannot be self-intersecting, can be concave. Mutually exclusive with [lat, long], and [north, south, east, west].
supplier	Restrict results to only the given space separated suppliers. Should match the “supplier” property of search results.
sort	Field to sort the result list by (omit for default)


?start=2020-01-01
&end=2020-02-01
&gsd=20
&lat=-33.8688
&long=151.2093
&north=-33.8247
&south=-33.855
&east=151.2405
&west=151.1821
&cloud=
&off-nadir=
&polygon=POLYGON((0,0 0,1 1,1 1,0 0,0))
&supplier=
&sort=date desc

Responses:

Occurs when your search has been successfully conducted. 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 /api/archive/order or /api/archive/order/batch endpoints.

Field	Type	Description
errors	array	A list of any errors that occurred during searching.
results	array	List of search results.

{
  "Errors": [
    "Supplier B encountered an error and was unable to respond"
  ],
  "results": [
    {
      "annotations": [
        "PONT: Your Point search was enlarged to an area centered on your search to meet the suppliers Minimum Order Quantity of 4 square km"
      ],
      "area": 36842.9803,
      "azimuth": 340.62,
      "bands": [
        {
          "id": "P",
          "max": 680,
          "min": 500,
          "name": "Pan"
        }
      ],
      "bounding": [
        [
          [
            151.00074930000005,
            -33.727445099999954
          ],
          [
            151.2296146000001,
            -33.75768747999996
          ],
          [
            151.23168390000012,
            -33.93079163999994
          ],
          [
            151.00089270000012,
            -33.899869199999955
          ],
          [
            151.00074930000005,
            -33.727445099999954
          ]
        ]
      ],
      "bundles": [
        {
          "bands": [],
          "key": "pan",
          "name": "Panchromatic",
          "price": 2000
        }
      ],
      "center": {
        "lat": -33.82894835499995,
        "long": 151.1157351250001
      },
      "cloud": 72.19,
      "date": "2018-01-03T23:44:15.251922Z",
      "fulfillmentTime": 168,
      "gsd": 15,
      "imageMode": "pushbroom",
      "licenses": [
        {
          "href": "http://example.com/license.pdf",
          "loadingAmount": 0,
          "loadingPercent": 10,
          "name": "Internal Use"
        }
      ],
      "offNadir": 0,
      "orderingID": "eyJhb...AYTqwM",
      "overlap": {
        "area": 4.0628,
        "percent": 100,
        "polygon": [
          [
            [
              151.1813667003777,
              -33.89951101365903
            ],
            [
              151.1813667003777,
              -33.91940891477645
            ],
            [
              151.20126460150223,
              -33.91940891477645
            ],
            [
              151.20126460150223,
              -33.89951101365903
            ],
            [
              151.1813667003777,
              -33.89951101365903
            ]
          ]
        ]
      },
      "platform": "landsat-8",
      "platformType": "satellite",
      "polarizations": [
        "unpolarized"
      ],
      "sceneID": "LC08_L2SP_089084_20180103_20200902_02_T2_SR",
      "sensorType": "multi-spectral",
      "supplier": "landsat",
      "thumbnail": "https://example.com/thumbnail.jpeg",
      "type": "scene"
    }
  ]
}

Occurs when your request is malformed.

No Example for Response Code: 400

Occurs when basic authentication details are missing or invalid.

No Example for Response Code: 401

The Search endpoint provides facilities to search Arlula and its suppliers for satellite imagery. It is highly recommended to use this endpoint preferentially when searching with a polygon, due to limitations on URL lengths.

post /api/archive/search

Request Body:

{
  "cloud": 80,
  "endDate,": "2018-05-06T00:00:00",
  "gsd": 5,
  "latLong": {
    "lat": 6,
    "long": 12
  },
  "offNadir": 15,
  "platformTypes": [
    "satellite"
  ],
  "polarizations": [
    "unpolarized"
  ],
  "sensorTypes": [
    "spot",
    "pushbroom"
  ],
  "sort": {
    "ascending": false,
    "field": "date"
  },
  "spectralRanges": [
    "vis",
    "nir"
  ],
  "startDate": "2018-02-18T00:00:00",
  "suppliers": "landsat sentinel-2"
}

Responses:

Field	Type	Description
errors	array	A list of any errors that occurred during searching.
results	array	List of search results.

{
  "Errors": [
    "Supplier B encountered an error and was unable to respond"
  ],
  "results": [
    {
      "annotations": [
        "PONT: Your Point search was enlarged to an area centered on your search to meet the suppliers Minimum Order Quantity of 4 square km"
      ],
      "area": 36842.9803,
      "azimuth": 340.62,
      "bands": [
        {
          "id": "P",
          "max": 680,
          "min": 500,
          "name": "Pan"
        }
      ],
      "bounding": [
        [
          [
            151.00074930000005,
            -33.727445099999954
          ],
          [
            151.2296146000001,
            -33.75768747999996
          ],
          [
            151.23168390000012,
            -33.93079163999994
          ],
          [
            151.00089270000012,
            -33.899869199999955
          ],
          [
            151.00074930000005,
            -33.727445099999954
          ]
        ]
      ],
      "bundles": [
        {
          "bands": [],
          "key": "pan",
          "name": "Panchromatic",
          "price": 2000
        }
      ],
      "center": {
        "lat": -33.82894835499995,
        "long": 151.1157351250001
      },
      "cloud": 72.19,
      "date": "2018-01-03T23:44:15.251922Z",
      "fulfillmentTime": 168,
      "gsd": 15,
      "imageMode": "pushbroom",
      "licenses": [
        {
          "href": "http://example.com/license.pdf",
          "loadingAmount": 0,
          "loadingPercent": 10,
          "name": "Internal Use"
        }
      ],
      "offNadir": 0,
      "orderingID": "eyJhb...AYTqwM",
      "overlap": {
        "area": 4.0628,
        "percent": 100,
        "polygon": [
          [
            [
              151.1813667003777,
              -33.89951101365903
            ],
            [
              151.1813667003777,
              -33.91940891477645
            ],
            [
              151.20126460150223,
              -33.91940891477645
            ],
            [
              151.20126460150223,
              -33.89951101365903
            ],
            [
              151.1813667003777,
              -33.89951101365903
            ]
          ]
        ]
      },
      "platform": "landsat-8",
      "platformType": "satellite",
      "polarizations": [
        "unpolarized"
      ],
      "sceneID": "LC08_L2SP_089084_20180103_20200902_02_T2_SR",
      "sensorType": "multi-spectral",
      "supplier": "landsat",
      "thumbnail": "https://example.com/thumbnail.jpeg",
      "type": "scene"
    }
  ]
}

Occurs when your request is malformed.

No Example for Response Code: 400

Occurs when basic authentication details are missing or invalid.

No Example for Response Code: 401

Thumbnail Details

The Thumbnail details endpoint returns the details of a scenes thumbnails as a tile map for rendering, allowing for easier presentation.

get /api/archive/thumbnail/details

URL Parameters:

* Required

Field	Description
id*	Ordering ID of the scene you wish to retrieve thumbnail details for.


?id=eyJhb...AYTqwM

Responses:

Details describing a set of tile that make up the total thumbnail for a given scene and supporting its rendering for presentation.

No Example for Response Code: 200

Occurs when your request is malformed.

No Example for Response Code: 400

Occurs when basic authentication details are missing or invalid.

No Example for Response Code: 401

The Thumbnail details endpoint returns the details of a scenes thumbnails as a tile map for rendering, allowing for easier presentation.

post /api/archive/thumbnail/details

Request Body:

Field	Type	Description
id	string	Ordering ID of the scene you wish to retrieve thumbnail details of.

No Example for request body

Responses:

Details describing a set of tile that make up the total thumbnail for a given scene and supporting its rendering for presentation.

No Example for Response Code: 200

Occurs when your request is malformed.

No Example for Response Code: 400

Occurs when basic authentication details are missing or invalid.

No Example for Response Code: 401