Arlula API Documentation
Overview
The Arlula infrastructure is broken down into a few main sections, each relating to distinct actions including accessing, purchasing, managing, and utilising satellite imagery data from archival and tasking sources.
This documentation serves as a comprehensive resource to best understand the platform and its associated endpoints.
If you would instead rather work with an SDK in your preferred language, we have a Python and NodeJS SDK available. If you are using another language, please let us know.
General information about authentication and connection testing can be found below, along with a changelog for major updates.
The following are the four main API groups, and their main endpoints:
Archive API: for querying and purchasing satellite imagery captured some time in the past.
This includes the ability to:
- Search, for obtaining a list of satellite imagery available for the request’s search criteria
- New order, which creates a new order, and pays for purchasing imagery
- Batch Order, for ordering multiple scenes at the same time
Tasking API: for querying availability and ordering satellite imagery to be captured in the future.
- Search, for obtaining a list of possible capture opportunities for a target location, time period and conditions
- Order, for confirming and booking one of the opportunities obtained from search
- Batch Order, for confirming and booking a set of tasking opportunities in a single operation.
Orders API: for managing and downloading your past imagery orders.
- 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
Collections API: for creating and managing collections of imagery that can be queried and explored as a discrete dataset.
- List Collections, which will list all collections on your account
- Collection Details, which will provide the details of an individual collection
- List Collection Items, which will list items (orders and scenes) within the collection
- Collection Item Details, which will provide details of an individual item within the collection
- Search Collection, which provides query and search functionality to find items within a collection
- Create Collections, for creating new data collections
- Add Collection item, to add orders to a collection
- Remove Collection Item, to remove them from the dataset
- Update Collection, to update labelling and descriptive details of the collection
- Delete Collection, to delete a collection
- Request Item Access, to request access to an order in a collection
- Collection Conformance, to view STAC standards compliance of the collection system
API Authentication
Making requests to the Arlula APIs requires providing API Authentication credentials for every request as part of the request header.
To obtain API credentials, you will need to create and API account in our system dashboard and be issued with API Credentials.
All requests to the API must be made via a https connection
Authentication is achieved by providing your API Key and API Password using the HTTP Basic Auth Mechanism.
Connection 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.
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
aoiwhich 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)
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
Version 2022-07
- Archive search request “res” parameter renamed to “gsd”
- Archive search response is now object rather than result array
- Removed archive search result eula and price fields
- Renamed archive search result field “id” to “orderingID” and “resolution” to “gsd”
- Increased polygon arrays to depth 3 for archive search result “bounding” and “overlap.polygon” to support complex polygons
- Added new archive search result fields “bands” for spectral resolution information, “bundles” for ordering level selection, and “licenses” for licensing selection.
- Deprecated “seats” as a field on archive order request
- Added “bundleKey” in archive order request to select processing level by key
- Order structure “imageryID” field renamed to more representative “orderingID”
Version 2023-01
- support to search by polygon
Version 2023-06
- batch archive ordering
- archive search via POST request
- collections system
Version 2023-08
- Tasking API
- Archive search sort parameter
Dashboard Documentation
Overview
The Dashboard infrastructure is broken down into a few main sections, each relating to distinct actions including accessing, purchasing, managing, and utilising satellite imagery data from archival and tasking sources.
This documentation serves as a comprehensive resource to best understand the platform.
Account Management: for user and account information.
- Account Details and Settings, for viewing and updating user and account information.
Team Management: for Team information and management.
- Team List, for viewing teams which you are either a member or administrator.
- Team Details, for management of a team.
Organisation Management: for Organisation information and management.
- Organisation List, for viewing organisations which you are either a member or administrator.
- Organisation Details, displays and allows management of organisation details.
- Organisation Members, displays and allows management of users in an organisation.
Order Management: for managing and downloading your past imagery orders.
- Order History, which will list all orders on you own or have been shared with you.
- Order Details, which will provide the details of an individual collection
Collection Management: for creating and managing collections of imagery.
- Imagery Collections, which will list all collections you own or have been shared with you.
- Collection Details, which will provide the details of an individual collection.
- Collection Items List, view all of the items in the collection that you have access to.
API Account Management: for querying imagery.
- API Account Setup, for creating an API account
- API Account List, which will list all API Accounts you have permission to
- API Account Details, for details and management of an API account.
- Update Whitelist, for details and management of an API accounts whitelist.
- Update Listeners, for details and management of an API accounts listeners.
- API Account Activate, for “activating” your API Account.
- API Account Credentials Rotate, for changing the credentials for an API account.
Billing Management: for managing and downloading your past imagery orders.
- Billing Account List, which will list all Billing accounts you have access to
- Billing Account Details, for details and management of a specific billing account.
- Create Billing Account, which allows creating of a new billing account.
Geostack Documentation
Overview
The Geostack infrastructure is broken down into a few main sections, each relating to distinct actions including searching Archive satellite imagery and scheduling new Tasking imagery .
This documentation serves as a comprehensive resource to best understand the platform.
Archive Search: for the searching of Arlula and its suppliers catalogue of archival satellite imagery.
- Location, for selecting an Area of Interest.
- Response Details, for viewing search results
- New Archive Order, for selecting imagery and placing an order.
Tasking Search: for searching of Arlula and its suppliers to view available capture opportunities and purchase imagery to be captured at a future date based on your requirements.
- Location, for selecting an Area of Interest.
- Response Details, for viewing search results
- New Tasking Order, for selecting captures and placing an order request.
Cart: for viewing selected orders and completing purchases.
Archive Search
The Archive Search allows the searching of Arlula and its suppliers catalogue of archival satellite imagery.
A search can be completed with query parameters in the left hand side bar. Query parameters include:
- Date or interest period: Archive imagery must be in the past.
- Location or area of interest
- Resolution
- Suppliers
- Off nadir angle
- Cloud cover percentage
Location
The area of interest can be provided in 5 ways:
- Search a point location using either an address, name, or coordinates.
- The Point Tool allows you to drop a pin at a location of interest
- The Bounding Box allows you to define an interest area by drawing a box
- The Polygon Tool allows you to define an area of interest by drawing a polygon.
- The File Upload Tool allows you to upload a KML, WKT or GeoJSON file containing one or more polygons.
Response Details
When the search is run, the left-hand side bar will display a list of Search Results.
Each result displays:
- Date of capture
- Scene reference
- Data Source
- Resolution
- Number of bands
- Estimated delivery time
- Price
- Thumbnail
Results can be sorted using the “Sort By” and “Direction” box. Archive imagery can be sorted by Price, Capture Date, GSD, Cloud, and Off Nadir.
To view more information, select the arrow next to the desired result. The “More Information” window will appear. This window displays:
- Supplier
- Scene Reference
- Off Nadir Angle
- Area: The scene area and the order area
- Cloud Coverage
- Percentage Overlap: how much of the scene overlaps with the selected AOI
- Bands
- Available Bundles and Licenses
To view the image on the map, select “Show on Map”.
New Archive Order
When you find an image that is appropriate for your needs, select “Add to cart” in the bottom right hand corner of the result. The Add Scene to Cart window will open. Here you can specify the desired bundle of bands, applicable license, and review the pricing. Complete the scene selection by clicking the “Add to Cart” button in the lower right hand corner of the window.
Tasking Search
The Tasking Search allows the searching of Arlula and its suppliers to view available capture opportunities and purchase imagery to be captured at a future date based on your requirements.
Search can be completed with query parameters in the left hand side bar. Query parameters include:
- Date or interest period: Tasking dates must be in the future
- Location or area of interest
- Resolution
- Suppliers
- Off nadir angle
- Cloud cover
Location
The area of interest can be provided in 5 ways:
- Search a point location using either an address, name, or coordinates.
- The Point Tool allows you to drop a pin at a location of interest
- The Bounding Box allows you to define an interest area by drawing a box
- The Polygon Tool allows you to define an area of interest by drawing a polygon.
- The File Upload Tool allows you to upload a KML, WKT or GeoJSON file containing one or more polygons.
Response Details
When the search is run, the left-hand side bar will display a list of Search Results.
Each result displays:
- Day or night image
- Capture Date Range
- Data Source
- Resolution
- Number of bands
- Maximum off-nadir angle
- Price
- Thumbnail
Results can be sorted using the “Sort By” and “Direction” box. Tasking results can be sorted by Price, GSD, capture Start Date and capture End Date.
To view the potential cover area on the map, select “Show on Map” .
New Tasking Order
When you find an opportunity that is appropriate for your needs, select “Add to cart” in the bottom right hand corner of the result. The Add Tasking Request to Cart window will open. Here you can specify the desired bundle of bands, applicable license, select priority, and review the pricing. Complete the tasking request by clicking the “Add to Cart” button in the bottom of the window.
Cart
This window displays all of the items in your cart. Here you can edit or delete existing items in the cart, and complete the order.
Complete the order with the “Confirm Order” button in the lower right of the window. An order confirmation window will appear detailing the pricing and licensing one last time. Agree to the supplied End User License Agreements, and then select “Place Order”. You will need to set-up or log in to your Arlula account to complete the order.
Once created, the order may return several different Order Status to indicate its current state of completion. When the order is “Complete”, it will be available to Download from the Arlula Dashboard.