Ursa Space's Imagery Ordering API is available through the Amazon Data Exchange (ADX)
Table of Contents
Endpoints:
Summary
Ursa Space image ordering is now available on the AWS Data Exchange (ADX). ADX subscribers gain API access to place orders for items in Ursa Space’s archive catalog, and task future collections with a subset of vendors in Ursa Space’s virtual constellation of satellite vendors. Orders are billed per-request through ADX’s new Metered Billing service.
Ursa Space maintains robust partnerships with existing and upcoming commercial data providers, and regularly ingests and processes a variety of SAR and non-SAR (i.e. optical, infrared, multi-spectral, and hyperspectral) data from this group of vendors in what is referred to as the Virtual Constellation.
Ursa Space performs this processing through the development and deployment of the Ursa Platform. The platform contains the data and software services required to ingest data (SAR imagery, optical imagery, external data sources for algorithmic fusion, etc.), run analytics and algorithms on these data to produce results, and provide customer access to related data feeds via API.
In addition to ingesting, cataloging, and normalizing data from vendors in the Virtual Constellation, Ursa Space is also able to rapidly task new imagery and deliver the resulting data to customers. Users may place purchase requests to schedule a SAR collection at a future date, or purchase existing imagery from the archive catalog containing over 18 million SAR and optical images.
This listing contains API access to place orders for items in Ursa Space’s archive catalog, and task future collections with a subset of vendors in our Virtual Constellation. User-specified parameters in new image tasking are limited in this API for simplicity. For more advanced tasking parameters and options, please contact Ursa using the support contact below.
This document describes the API and service endpoints which will allow external Ursa Space users to order and request data from Ursa’s Virtual Constellation. These endpoints support ordering data from existing vendor catalogs (archive imagery), tasking new images, retrieving status of existing orders, and retrieving presigned S3 URLs for downloading delivered imagery. The workflow from placing an order to downloading a delivered image is described below.
Workflow Overview
This section provides a high-level overview of the steps involved in purchasing imagery via ADX endpoints. More detail about each endpoint is provided below.
-
Retrieve the price of an order through the POST /ios/order/price endpoint before purchasing.
-
Place an archive catalog or new tasking order through the POST /ios/order endpoint.
-
Note: Both archive catalog and new tasking orders are requested through the same endpoint.
-
Upon success, the response will include an orderId as well as information about the order itself.
-
A confirmation email will also be sent to the contactEmail provided in the request.
-
Order status and other order information is retrieved from the GET /ios/order/{orderId} endpoint.
-
The statusHistory field contains a list of order statuses, with the current status as the last entry. Possible order states are enumerated at the end of this document.
-
The products field contains a list of productIds that will be used in later endpoints. Currently there will be only a single productId per order.
-
At any time, users can retrieve all orders associated with their account via the GET /ios/order endpoint.
-
Information about specific products associated with an order can be accessed through the GET /ios/order/{orderId}/product/{productId} endpoint.
-
Products contain an images field that provides a list of all images associated with your order and metadata information associated with each image.
-
When the order is complete and imagery is available for download, an email will be sent to the email specified in the contactEmail of the initial order request.
-
Upon order completion, a user can retrieve what is referred to as the blobId for specific images that are available for download through the GET /ios/order/{orderId}/product/{productId}/deliveries endpoint.
-
A list of deliveryItems will contain IDs for each image available to be downloaded by the user. The blobId is used for downloading the image.
-
The statusHistory field contains a list of statuses for each set of delivery items (separate from the order status). The possible statuses are enumerated below.
-
Note: images cannot be retrieved until the status is delivered.
-
User can retrieve a link to their image using the endpoint GET /ios/order/{orderId}/download/{blobId}/url
-
The endpoint will return a presigned URL generated for a specific image. The presigned URL will be available for 5 minutes after generation.
Note: For an image to be downloaded through this endpoint, the delivery item’s state must be delivered.
Endpoints: Place an Order for a Catalog Image
This endpoint enables authorized users to place an order for one or more catalog/archive images. Images are specified using assignedIds returned by queries to the Ursa Space catalog. For more information, see our Ursa Space – SAR Catalog Search ADX product.
An example request and response are presented on the next page. In the request body:
-
The field assignedIds must be one or more available-image assigned IDs from the imagery catalog.
-
The type field is a required field and must have the value catalog for catalog/archive orders.
-
The descriptiveName, purchaseReason, and customerNotes fields are all optional.
-
The contactEmail will receive an email confirmation at the time of order creation and order completion.
In the response body:
-
The id field returned in response to an order request is the Order ID that can be used for future reference.
-
The products field refers to the products attached to that specific order. Currently each order will have a maximum of one product, which can be used in the subsequent GET endpoints.
-
The statusHistory indicates the history of states for the order, with the final state being the current state of the order. See order state enumerations at the end of this document.
-
The request field is an ID that can be used in the GET /ios/order/request/{requestId} endpoint to retrieve the original request.
-
The owner field is the UUID associated with the user creating the order. The customer field is the UUID for the customer/company the user is associated with (multiple users can be associated with a single customer).
In the response header:
-
The x-amz-dataexchange-metering header in the response will indicate the cost of the order. It will have a value of OrderPrice=XX.0 where XX is the cost of the order.
Method: POST
Path: /ios/order
Request Body:
{
“descriptiveName”: “string”,
“purchaseReason”: “string”,
“customerNotes”: “string”,
“request”: {
“type”: “catalog”,
“assignedIds”: [
“3fa85f64-5717-4562-b3fc-2c963f66afa6”
]
“contactEmail”: “user@example.com”
}
}
Response Code: 201: A new order has been created
Metered Billing Response Header:
“x-amz-dataexchange-metering”: “OrderPrice=100.0”
Response Body:
{
“id”: “1234-5678-9012”,
“descriptiveName”: “string”,
“purchaseReason”: “string”,
“customerNotes”: “string”,
“request”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“owner”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“customer”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“contract”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“products”: [
“3fa85f64-5717-4562-b3fc-2c963f66afa6”
],
“statusHistory”: [
{
“state”: “created”,
“when”: “2022-05-11T14:51:52.443Z”
}
]
}
Endpoints: Place an Order for a Tasking Image
This endpoint enables authorized users to place an order for tasking new images. Ursa will deliver a SCID file, GEC file, and GTC file for each successful tasking order.
In the request body:
-
The field assignedIds must be one or more available-image assigned IDs from the imagery catalog.
-
The type field is a required field and must have the value tasking-parameters for tasking orders.
-
The descriptiveName, purchaseReason, and customerNotes fields are all optional.
-
The contactEmail will receive an email confirmation at the time of order creation and order completion.
-
In the aois field, we currently only support a single AOI of type point, with a latitude, longitude, and radius.
-
In the schedule field, we currently only support a single schedule of type range, with a minimum and maximum datetime.
-
The collectionParameters field is a list, but we currently only support a single collection parameter entry per request (the size of the list must be 1). The collection parameter fields are:
-
The type field is required and currently must be set to “sar”.
-
The imagingMode field is required and determines the price of the tasking request. The field is a map with two inputs:
-
constraint: one of the available imaging modes, enumerated at the end of this document.
-
level: this field must be set to “required”.
-
-
The response body and Metered Billing response header will be in the same format as catalog order responses.
Method: POST
Path: /ios/order
Request Body:
{
“descriptiveName”: “string”,
“purchaseReason”: “string”,
“customerNotes”: “string”,
“request”: {
“contactEmail”: “user@example.com”,
“type”: “tasking-parameters”,
“aois”: [
{
“type”: “point”,
“latitude_deg”: 0,
“longitude_deg”: 0,
“radius_km”: 0
}
],
“schedule”: [
{
“type”: “range”,
“range”: {
“min”: “2022-05-11T14:51:52.443Z”,
“max”: “2022-05-11T14:51:52.443Z”
}
}
],
“collectionParameters”: [
{
“type”: “sar”,
“imagingMode”: {
“constraint”: “SPOTLIGHT”,
“level”: “required”
}
}
]
}
}
Response Code: 201: A new order has been created
Metered Billing Response Header:
“x-amz-dataexchange-metering”: “OrderPrice=100.0”
Response Body:
Response body will be in the same format as catalog order responses.
Endpoints: Price an Order Before Purchase
This endpoint will return the price of an order without placing the order or charging the customer.
Method: POST
Path: /ios/order/price
Request Body:
Same request body as catalog or tasking order.
Response Code: 200 : OK
Response Body for Catalog Orders:
{
“catalogPrice”: {
“3fa85f64-5717-4562-b3fc-2c963f66afa6“: 1000.00,
“ab533203-9115-4327-ac9a-58f1d148ee44”: 1200.00
}
}
Response Body for Tasking Orders:
{
“taskOrderPrice”: 1550.00
}
Endpoints: Get Order Status
This endpoint will return an order and its status for a given order ID.
-
The products field refers to the products attached to that specific order. Currently each order will have a maximum of one product, which can be used in the subsequently described GET endpoints.
-
The statusHistory indicates the history of states for the order, with the final state being the current state of the order. See order state enumerations at the end of this document.
-
The request field is an ID that can be used in the GET /ios/order/request/{requestId} endpoint to retrieve the original request.
-
The owner field is the UUID associated with the user creating the order. The customer field is the UUID for the customer/company the user is associated with (multiple users can be associated with a single customer).
Method: GET
Path: /ios/order/{orderID}
Request Body: None
Response Code: 200 : OK
Response Body:
{
“id”: “1234-5678-9012”,
“descriptiveName”: “string”,
“purchaseReason”: “string”,
“customerNotes”: “string”,
“request”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“owner”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“customer”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“products”: [
“3fa85f64-5717-4562-b3fc-2c963f66afa6”
],
“statusHistory”: [
{
“state”: “created”,
“when”: “2022-05-11T14:51:52.443Z”
}
]
}
Endpoints: Get All User Orders
Get all orders associated with the user making the request. The response will be a list of orders in the format of orders retrieved from GET /ios/order/{orderId}.
Method: GET
Path: /ios/order
Request Body: None
Response Code: 200 : OK
Response Body:
[
{
“id”: “1234-5678-9012”,
“descriptiveName”: “string”,
“purchaseReason”: “string”,
“customerNotes”: “string”,
“request”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“owner”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“customer”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“products”: [
“3fa85f64-5717-4562-b3fc-2c963f66afa6”
],
“statusHistory”: [
{
“state”: “created”,
“when”: “2022-05-11T14:51:52.443Z”
}
]
},
{
“id”: “2345-6789-0123”,
“descriptiveName”: “string”,
“purchaseReason”: “string”,
“customerNotes”: “string”,
“request”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“owner”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“customer”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“products”: [
“3fa85f64-5717-4562-b3fc-2c963f66afa6”
],
“statusHistory”: [
{
“state”: “created”,
“when”: “2022-05-11T14:51:52.443Z”
}
]
}
]
Endpoints: Get Order Request
Get a request using the request ID returned in a POST /ios/order or GET /ios/order/{orderId} call.
Method: GET
Path: /ios/order/request/{requestId}
Request Body: None
Response Code: 200 : OK
Response Body:
JSON request in format provided to POST /ios/orderEndpoints: Get Product Status
This endpoint retrieves the product associated with a specific orderId. The product will look slightly different depending on if the order is a catalog order or a new tasking order. Both types of products will contain:
-
The id and order fields showing the IDs requested in the endpoint path
-
An orderDeliveries field that will contain an ID to access deliveries when they are available.
-
Note: this field will initially be empty when the order is first created. It will get populated as the order is fulfilled by Ursa.
-
Note: this field is a list, but currently we support a single orderDelivery ID per product.
-
-
The statusHistory indicates the history of states for the product, with the final state being the current state of the product. See product state enumerations at the end of this document.
-
Note: this is a separate status from the individual deliveryItem statuses described below.
-
In catalog order requests, the following product fields will contain catalog-specific values:
-
The type field will have a value of “OrderProduct”
-
The images field will have images of type “priced-image”. This will contain metadata about the ordered images as well as their price and currency.
In tasking order requests, the product will have fields:
-
The type field will have a value of “taskingOrderProduct”
-
The images field will have images of type “Image”. This will contain image metadata, but no price or currency.
-
Note: the images field will initially be empty and will be populated as tasking requests are fulfilled.
-
-
A taskingOrders field with:
-
imagingMode, the determining factor in the price of a tasking request.
-
price and currency of the tasking request.
-
Method: GET
Path: /ios/order/{orderID}/product/{productID}
Request Body: None
Response Code: 200 : OK
Response Body for Catalog Order Products:
{
“type”: “OrderProduct”,
“id”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“order”: “1234-5678-9012”,
“orderDeliveries”: [ “3fa85f64-5717-4562-b3fc-2c963f66afa6” ],
“statusHistory”: [ { “state”: “created”, “when”: “2022-05-12T18:47:37.661Z”, } ],
“images”: [
{
“type”: “priced-image”
“assignedId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“startTimeUTC”: “2022-05-12T18:47:37.661Z”,
“vendor”: “CAPELLA”,
“vendorMode”: “CAP_SPOTLIGHT”,
“resolution”: “0.25m”,
“wkt”: “MULTIPOLYGON(((-76.582054 42.4832555,-76.448844 42.499964,-76.430992 42.395082,-76.558708 42.388490,-76.582054 42.483255)))”,
“price”: 3163,
“currency”: “USD”
}
]
}
Response Body for Tasking Order Products:
{
“type”: “taskingOrderProduct”,
“id”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“order”: “1234-5678-9012”,
“orderDeliveries”: [ “3fa85f64-5717-4562-b3fc-2c963f66afa6” ],
“statusHistory”: [ { “state”: “created”, “when”: “2022-05-12T18:47:37.661Z”, } ],
“taskingOrders”: [
{ “imagingMode”: “SPOTLIGHT”, “price”: 2500, “currency”: “USD” }
],
“images”: [
{
“type”: “Image”,
“assignedId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“startTimeUTC”: “2022-05-12T18:44:50.358Z”,
“vendor”: “CAPELLA”,
“vendorMode”: “CAP_SPOTLIGHT”,
“resolution”: “0.25m”,
“wkt”: “MULTIPOLYGON(((-76.582054 42.4832555,-76.448844 42.499964,-76.430992 42.395082,-76.558708 42.388490,-76.582054 42.483255)))”
}
]
}
Endpoints: Get Delivery Items
This endpoint gets all delivery items for a given productId in an order.
-
Currently, each order will have at most one productId. Each product is a list of json objects (“deliveries”) that each have a number of deliveryItems. Currently, each product will have at most one “delivery” (the list will be of size 1), but that delivery can have multiple deliveryItems as shown below.
-
Each deliveryItem will have a format and a where field:
-
The format field indicates the format of the delivered image.
-
The where field will always be of type “platform” for ADX users and contain an assignedId of the image and a blobId to be used in the download endpoint below.
-
-
The statusHistory indicates the history of states of the delivery, with the final state being the current state of the delivery. See delivery state enumerations at the end of this document.
Method: GET
Path: /ios/order/{orderID}/product/{productID}/deliveries
Request Body: None
Response Code: 200 : OK
Response Body:
[
{
“id”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
“deliveryItems”: [
{
“format”: “SLC_SICD”,
“where”: {
“type”: “platform”,
“assignedId”: “304907be-dd03-4990-bb80-7eaad3bfc61a”,
“blobId”: “2cb8db8e-224b-4419-a676-76488ae90e2c”
}
},{
“format”: “GEC”,
“where”: {
“type”: “platform”,
“assignedId”: “304907be-dd03-4990-bb80-7eaad3bfc61a”,
“blobId”: “4f388f22-5b79-4ef7-b575-9d2f29486a84”
}
},{
“format”: “GTC”,
“where”: {
“type”: “platform”,
“assignedId”: “304907be-dd03-4990-bb80-7eaad3bfc61a”,
“blobId”: “fc39fab3-cfeb-4111-ba6c-d526d133854d”
}
},
],
“statusHistory”: [
{ “state”: “creating”, “when”: “2022-05-12T12:29:35.224Z”, }
]
}
]
Endpoints: Download Image From Blob
Generates a presigned URL for a specific image blobId and returns that URL in the response body. The URL will be valid for 5 minutes after creation.
-
An order’s blobIds can be retrieved via the GET /ios/order/{orderID}/product/{productID}/deliveries described above.
-
Note: the delivery item must be in the state “delivered” for URL retrieval to work.
Method: GET
Path: /ios/order/{orderID}/download/{blobID}/url
Request Body: None
Response Code: 200: OK
Response:
https://s3.amazonaws.com/presigned-url
Enumerations
Imaging Mode Collection Parameter
|
Imaging Mode |
|---|
|
SPOTLIGHT |
|
STRIPMAP |
Order StatusHistory States
|
Order State |
Description |
|---|---|
|
created |
Order has been created and is waiting for the next step |
|
open |
Ursa internal-only state |
|
payment-pending |
Payment is needed for the order to progress |
|
in-progress |
Order is ready to be fulfilled by the Ursa delivery team |
|
cancelled |
Order has been cancelled |
|
under-review |
Order is currently under review by the Ursa delivery team |
|
accepted |
Order has been approved and is ready for delivery |
|
closed |
Order has been rejected |
|
completed |
Order has been fulfilled and delivered to the customer |
Product StatusHistory States
|
Product State |
Description |
|---|---|
|
created |
Product item has been created |
|
completed |
Product has been delivered successfully |
Delivery StatusHistory States
|
Delivery State |
Description |
|---|---|
|
creating |
Delivery item is being created |
|
delivered |
Delivery item is delivered and ready to be retrieved by the customer |