Arlula NodeJS/TS SDK
The Arlula NodeJS SDK provides convenient access to the Arlula satellite imagery APIs.
Links
The full API reference documentation is available on the arlula website
https://arlula.com/documentation/
The package can be found on npm at
https://www.npmjs.com/package/@arlula/core
The source can be found on github at
https://github.com/Arlula/nodejs-core-sdk
Credentials
Before using the SDK, you will need to create an API account and have its credentials.
These can be created from the account dashboard at https://api.arlula.com/;
Installation
Install the package with:
npm install arlula --save
Usage
Setup and Connect
To use the SDK, you will first need to initialized a connection to the server
import Arlula from "@arlula/core";
const client = new Arlula("<your API Key>", "<your API Secret>");
Once created its best to test the connection to ensure your credentials are correctly entered
client.test()
.then((ready) => {
console.log(ready);
});
Requests
Archive Imagery
The archive imagery API allows the searching of catalogs of previously captured satellite imagery, and the ordering of those scenes.
To access the archive imagery API,
client.archive()
Search
Search available Archive imagery by creating and sending a search request
import SearchRequest, { GroundSampleDistance } from "@arlula/core/archive/search-request";
const request = new SearchRequest(new Date("2020-08-16"));
request.point(151.209439, -33.854259);
request.setMaximumGSD(GroundSampleDistance.medium)
client.archive().search(request)
.then((scenes) => {
console.log(scenes);
});
The search request will return a SearchResponse object, containing an array of available scenes as SearchResult objects (see structure reference), or any errors returned by the request.
Searches can be done by a target date, date range, point and bounding box searches, as well as restricting the maximum allowable ground sample distance.
Full details on constructing searches is available below.
Order
Once you've found a scene that suits your purpose, you can order the imagery.
Ordering can either be done using a SearchResult object, or the value of its id field.
import OrderRequest from "@arlula/core/archive/order-request";
const request = new OrderRequest("<scene id>", "<selected license eula>", "<selected bundle key>");
client.archive().order(request)
.then((order) => {
console.log(order);
})
Ordering requires confirming the eula of the supplier for the given scene, the URL of the eula can be found in the search result.
Similarly, the number of seats to license the image for must be provided, and may affect pricing (see API documentation for details on eulas and pricing).
NOTE: search results have a fulfillment field which estimates how long it will take the supplier to provide the imagery for the order.
The imagery will not be available immediately in the promise for all suppliers
Search Requests
Search requests consist of a request for scenes subject to a spatial and temporal constraint.
These constraints can take several forms, which can be controlled by chaining methods on the search request.
Search requests can be initialized without any details, or with an initial date for a single date search, or as the start date for a date range
import SearchRequest from "@arlula/core/archive/search-request";
req = new SearchRequest();
// or
req = new SearchRequest(new Date("2020-12-16"));
After initializing the search request, its details can be controlled by several methods.
The temporal constraints can be controlled with the following methods;
-
atDate(date)-------------> discards any date range and sets a single date search to the given date -
from(date)---------------> sets the search date, or start of a date range (ignoring any set end date) -
to(date)-----------------> sets the end date of a date range (converting a single date search to a range) -
betweenDates(start, end)-> discards all current dates and sets a date range to search
To constrain the search in space and search your specific area of interest, you can specify with the following methods;
-
point(long, lat)----------------------> set the center point of your area of interest with its latitude and longitude -
boundingBox(west, north, east, south)-> set a bounding box containing your area of interest by its cardinal boundaries
Additionally, if you're only interested in results of a certain ground sample distance, you can specify a maximum GSD for search results.
You can specify a GSD in meters/pixel, or use the labels of predefined common sample distances in the GroundSampleDistance enumeration
import { GroundSampleDistance } from "@arlula/core/archive/search-request";
req.setMaximumGSD(GroundSampleDistance.high)
// or
req.setMaximumGSD(3)
Results can also be filtered by the imagery source, or properties such as
-
withSupplier("<supplier key>")--> Limit results to only the identified supplier -
withCloudCover(cloudPercentage)-> Limit results to those with a whole scene cloud coverage less than the provided percentage -
withOffNadir(OffNadirAngle)-----> Limit results to only those with an off nadir pointing within ± the provided value
Lastly, these calls may be chained to generate your request, i.e.
req = new SearchRequest(new Date("2020-12-16")).to(new Date("2020-12-30")).point(151.209439, -33.854259).withCloudCover(50);
Order Requests
In addition to creating an order request with its id/search request, eula and seat count; details of webhooks and emails to notify of status changes and completion of the order can be provided.
Both in the constructor
import OrderRequest from "@arlula/core/archive/order-request";
req = new OrderRequest("<id>", "<eula>", <seats>, [<webhooks...>], [<emails...>])
or may be set/added to via methods on the order request;
-
setWebhooks(string[])-> removes all existing webhooks and adds the provided list -
addWebhook(string)----> adds a webhook to the existing list -
setEmails(string[])---> removes all existing emails and adds the provided list -
addEmail(string)------> adds an email to the existing list
Order management
The order management API allows viewing order details, and the downloading of completed orders resources
To access the order management API,
client.orders()
List Orders
List orders will show the history of all orders on your API account, sorted from most to least recent.
client.orders().list()
.then((orders) => {
console.log(orders);
});
Each order has an alias to execute the 'Get Order' request and load its resources, accessible via the method order.loadResources()
Get Order
Loads an identified order, along with its associated resources (if the order is complete)
client.orders().get("<order id>")
.then((order) => {
console.log(order.resources);
});
Each listed resource has an alias to execute the 'Download Resource' request and access the resources contents.
This is accessible via the method resource.download()
Download Resource
Resources can be downloaded in two ways, to a file on system, or to an in memory ArrayBuffer.
Before starting a download, check a resources size field and ensure it is not larger than the available memory of the application.
Download to Memory
Downloads the resources contents and presents it as an ArrayBuffer.
client.orders().downloadResource("<resource id>")
.then((body) => {
console.log(body);
})
Download to Disk
Download the resource piping the result to a file on disk, or creates a file at the provided path.
client.orders().downloadResourceToFile("<resource id>", "<filepath>")
.then((fileReference) => {
// use the resource file
})
or
const file = fs.createWriteStream("<filepath>", {
flags: "w+",
mode: 0o644,
});
client.orders().downloadResourceToFile("<resource id>", file)
.then((fileReference) => {
// use the resource file
// note: fileReference === file
})
Usage with TypeScript
A full set of types are exported by this package to ensure type safety in TypeScript environments, as well as to allow intellisense in most IDEs.
Beyond those covered above for search, ordering and their associated enumerations
import SearchRequest, { GroundSampleDistance } from "@arlula/core/archive/search-request";
// and
import OrderRequest from "@arlula/core/archive/order-request";
The return types and several of their enumerations are also exposed
// the search result object
import SearchResult from "@arlula/core/archive/search-result";
// orders and their status enumeration
import Order, { OrderStatus } from "@arlula/core/orders/order";
// resources and their supported legacy types enumeration (see documentation for new roles mechanism)
import Resource, { ResourceType } from "@arlula/core/orders/resource";