Your access to satellite imagery and analytic results
with no geographic, political, or weather-related limitations.
ADX_IMAGERY_ORDERING_API
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:
Endpoints: 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
Order StatusHistory States
Product StatusHistory States
Delivery StatusHistory States
BASIC_CHANGE_DETECTION
The main change detection product consists of “red fled, blue is new” color coded indicators of change objects. The product is available as a vector product (GeoJSON named product/blob.cd-geojson.json) and/or a raster product (GeoTIFF named product/blob.cd-red-blue-product.tif).
Sample output files available upon request.
GeoJSON
The GeoJSON file is stored as a FeatureCollection, with one Feature per change object. Each Feature in the FeatureCollection contains the following fields: type: always “Feature” geometry: defined as a standard GeoJSON Polygon geometry (with Polygon type). properties: a dictionary with the fields described in the following table
GeoTIFF
The GeoTIFF file is a geo-registered 4-band RGBA image that uses the WGS-84 projection. Pixels are colored blue to indicate an object that has arrived between the reference and match images; red to indicate an object that has departed between the reference and match images; and transparent to indicate that no significant change has taken place.
A “quick look” PNG image (named product/blob.cd-red-blue-product_quick_look.png) is also created to coincide with the GeoTIFF. Quick look reference (product/blob.cd-product_ref_quick_look.png) and match (product/blob.cd-product_match_quick_look.png) images are also provided.
CHANGE_INTENSITY_METRICS
The change intensity metrics product consists of a series of statistical and metadata fields that describe each change blob. These fields describe the statistical properties of each change blob, its area, spatial characteristics, etc. The product is available as a vector product (GeoJSON named product/blob.cd-geojson.json) and as a pair of CSV files.
When the change intensity product is selected as the output, the GeoTIFF/Quick Look PNG version of the change detection product, described in the previous section, can also be created.
Sample output files available upon request.
GeoJSON
The GeoJSON file is stored as a FeatureCollection, with one Feature per change object. Each Feature in the FeatureCollection contains the following fields: type: always “Feature” geometry: defined as a standard GeoJSON Polygon geometry (with Polygon type). properties: a dictionary with the fields described in the following table
CSV
The Change Intensity Metrics product is provided with a Change Intensity CSV file (named cd-change-intensity-csv/change_intensity_metrics.change_detection) that provides statistics on each detected change object in the imagery. The CSV file contains a column for each property that is included in the associated GeoJSON feature properties (i.e., the fields in the table in the previous section). The CSV file also includes a column (‘uuid’) to assign each change object a unique identifier. The Change Intensity Metrics product also includes a summary file CSV file (named cd-full-map-metrics-csv/full_map_metrics.change_detection) that provides a statistical summary of the areas of change objects detected in the scene (maximum, average, and standard deviation of arrivals, departures, and all changes). This file also provides the fraction of total change area that consisted of arrivals and departures, respectively, and the fraction of total scene area that consisted of arrivals and departures, respectively.
DELIVERY_TO_S3
Deliveries from Ursa Space Systems are posted to an Amazon Web Services (AWS) S3 bucket. This bucket is specific to your organization and owned and operated by Ursa Space Systems.
Setup
Prior to integration onboarding, you will send Ursa the AWS Account ID of the AWS account you will be using for integration with Ursa and receipt of deliveries. During integration onboarding, Ursa will provide you with:
our AWS Account ID
an External ID
Role Name
These three pieces of information are then used to access your deliveries in the S3 bucket. The External ID is a secret shared between you and Ursa and should be stored, handled, and transferred securely. Ursa will also provide you with the S3 bucket name in which you will receive deliveries. This bucket name will also be provided per delivery as part of the S3 URL.
Accessing your Deliveries
To access your deliveries, you can use the AWS Web Console, Command-Line Interface (CLI), or any supported client libraries in order to access the files, according to the provided link, in the S3 bucket. In order to access the S3 bucket, you will need to use AWS’s Security Token Service (STS) to assume the appropriate role.
How to Assume a Role in the AWS Web Console
Your AWS user must have STS:AssumeRole IAM permission to assume a role. Click the dropdown menu on your username in the main Ursa AWS account and click Switch Roles Enter the Account ID, Role, and Display name and click Switch Role To switch back, click the dropdown and click Back to (username)
For further information and for guidance on using STS in the AWS CLI or client libraries, refer to the AWS documentation: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html
IMAGERY_CATALOG_SEARCH
Ursa Space maintains many partnerships with existing and upcoming commercial data providers and regularly ingests and processes various processing levels 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 our 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 provides access to related data feeds via API.
One of the many data feeds the platform provides access to are the available data catalogs provided by these vendors. Available data consists of all the historical collections the vendors have collected and stored within their own proprietary systems. Ursa Space ingests and catalogs all of these collections together in one central repository within the platform by normalizing the fields of the metadata into a single schema. This means users may query across the virtual constellation using the same set of criteria without having to translate between different vendor formats.
The following describes the API and service endpoints which will allow external Ursa Space users to programmatically interact with the available data catalogs that exist within the platform.
Endpoints
The Ursa Space Imagery Catalog service can be queried using GraphQL. URL: https://platform.ursaspace.com/api/psdm/graphql Request Type: POST Headers: Authorization: Bearer <TOKEN> Content-type: application/json Request Data: GraphQL query for SAR Image Catalog of the form: Response Body: Content-type: application/json Information about order and current status Response JSON Data: SAR Image Catalog Response of the form: The fields within the “returned records” objects are specified in your query. (See examples below.) On error, you will receive a message like the following:
The <TOKEN> is the access_token acquired from the login endpoint.
GraphQL Query Details
QUERYPARAMS are any combination of the various fields in the metadata schema. Query parameters are defined as a multilevel dictionary. For example, to get all records that have been uploaded since December 1, the query params will be:
uploadTime: { gt: “2020-12-01T00:00:00Z” }
Note: All dates are UTC and in ISO-8601 format.
To query for records from a specific vendor:
content: { catalogProperties: { vendor: { eq: “EGEOS” } } }
Note: The only field that does not use a query operator is assignedId.
As part of the query parameters, you can limit the number of records in a response.
In your query, simply specify limit to specify the number of records to return. The following query returns 10 ICEYE SAR image catalog records:
As part of the query parameters, you can specify a field to sort by. To sort records by a specific field, use the sortBy query parameter. The sortBy query “object” contains two fields:
- field: a dot-separated path to the field to sort by
- sortOrder: either ASC or DESC
The query service returns a maximum of 5000 records in a single query and supports paging to retrieve datasets greater than 5000 records. When your dataset exceeds 5000 records, you can invoke the same query again but with an offset parameter, e.g.:
SAR Metadata Schema
SAR Catalog Enumerations
Within the SAR Image Catalog, some fields, such as vendor, are defined as enumerated values. This section lists those fields and valid input values:
IMAGE_PRODUCT_DELIVERY
When an order for an imagery product is delivered to you by Ursa:
You will be notified by Ursa via e-mail that the delivery is ready
The delivery will be available in an AWS S3 bucket owned by Ursa that has been configured prior to image delivery
You will be notified by Ursa via e-mail that the delivery is ready
The delivery will be available in an AWS S3 bucket owned by Ursa that has been configured prior to image delivery
Content of Delivery
The delivery consists of a single ZIP-format file. The filename will typically be image-id.zip, where image-id is a UUID identifying the image on the Ursa Platform (e.g., 02889306-e7fe-4fce-96ec-29de70158757.zip). The full S3 URL, including the filename of the delivery, will be provided by Ursa in the e-mail delivery notification (e.g., s3://ursa-external-yourcompany/02889306-e7fe-4fce-96ec-29de70158757.zip). This Zip file contains one file per image and image format (or ancillary data format). These are named using the convention BASENAME_FORMAT.EXT, where BASENAME is an image-specific filename, FORMAT is a short descriptor of the file format, and EXT is the file type extension. Standard file formats and extensions are listed in the table below:
IMAGERY_REQUEST_ORDER
You can request an image by emailing: image.services@ursaspace.com
When you request an image, provide the following information:
Financial Budget: How many dollars can be spent fulfilling the request?
Collection Quantity: <Single> or <Recurring Weekly/Monthly/Every Orbit/Every N Days>
Imaging Vendor: Optional. <Airbus> or <Capella> or <eGeos> or <ICEYE> or <MDA> or <SIIS>
Imaging Mode: <Stripmap> or <Spotlight> or Vendor-specific Mode. Optional if Image Resolution Provided.
Image Resolution (Min/Max): <XX.X to YY.Y meters> Optional if Imaging Mode provided.
Imaging Date Constraints: <YYYY-MM-DD through YYYY-MM-DD>
Incidence Angle Min/Max: Optional. Specify <XX-YY Degrees> if known.
Polarization: Optional. <HH> or <HV> or <VH> or <VV> Default to standard vendor mode if no requirement.
Location: <See Attached KML(s>) and attach as ZIP file, or Specify <(Lat, Lon) = (XX.XXXXX, YY.YYYYY)>
Delivery Formats: <SICD> and/or <GEC Projection> and/or <GTC Projection> and/or <POV Projection>
Other Constraints: Optional. Coherent Pairs, Noncoherent Pairs, InSAR, etc.
Financial Budget: How many dollars can be spent fulfilling the request?
Collection Quantity: <Single> or <Recurring Weekly/Monthly/Every Orbit/Every N Days>
Imaging Vendor: Optional. <Airbus> or <Capella> or <eGeos> or <ICEYE> or <MDA> or <SIIS>
Imaging Mode: <Stripmap> or <Spotlight> or Vendor-specific Mode. Optional if Image Resolution Provided.
Image Resolution (Min/Max): <XX.X to YY.Y meters> Optional if Imaging Mode provided.
Imaging Date Constraints: <YYYY-MM-DD through YYYY-MM-DD>
Incidence Angle Min/Max: Optional. Specify <XX-YY Degrees> if known.
Polarization: Optional. <HH> or <HV> or <VH> or <VV> Default to standard vendor mode if no requirement.
Location: <See Attached KML(s>) and attach as ZIP file, or Specify <(Lat, Lon) = (XX.XXXXX, YY.YYYYY)>
Delivery Formats: <SICD> and/or <GEC Projection> and/or <GTC Projection> and/or <POV Projection>
Other Constraints: Optional. Coherent Pairs, Noncoherent Pairs, InSAR, etc.
OIL_STORAGE_API
The Ursa Oil Storage RESTful API is split into three different endpoints. All interactions with this API will be via HTTP requests and must include a request header (note: Many web resources are available to learn about RESTful web interfaces, see here: https://spring.io/understanding/REST to start).
Each endpoint can take a number of different query fields and values as inputs. The following documentation supplies the basic format for queries, lists of the available query fields, and valid values for each. These are split into groups by the endpoint name.
Each request must include a bearer token in the request header (In the header supply a field: ‘Authorization’ with value: ‘Bearer <YOUR_UNIQUE_TOKEN>’). Your JSON Web Token can be retrieved by sending a POST request to the login endpoint with your credentials (described below).
We recommend a tool like Postman (Postman API Platform | Sign Up for Free ) for testing the API. Postman has documentation (Building requests | Postman Learning Center ) to walk through the process of making an API request.
The Oil data API requests take the general form:
https://portal.ursaspace.com/api/data/<endpoint name>/find?<params>
Additional documentation on each endpoint and valid query fields and values are covered in the remained of this document.
To use this API with Python, you will need to leverage a library like Requests to interact with the REST service and jq to parse the JSON response object.
Note: In this document when annotations in brackets (< >) are used, that indicates a user defined bit of data. Replace the whole <text> with your data. Example <this year> becomes 2018, and “<this year>” becomes “2018”. Note: In our URL based requests, no quotes are used around any values, but you will see quotes in JSON responses.
Login Endpoint: /api/pas/login?
To utilize the login endpoint, make a POST call including the username and password. A valid token will be returned. The login endpoint general request form is: https://portal.ursaspace.com/api/pas/login The body should contain Key value pairs for user and password as well as setting the grant_type to password username <your user name> password <your password> grant_type password Here is an example HTTP Request: POST /api/pas/login? HTTP/1.1 Host: portal.ursaspace.com cache-control: no-cache username=<your username>password=<your password>grant_type=password Here is an example cURL: curl -X POST \ https://portal.ursaspace.com/api/pas/login \ -H ‘cache-control: no-cache’ \ -d ‘username=<your username>&password=<your password>&grant_type=password’ Note: Postman can help you figure out which special characters need encoding for a variety of languages when making REST calls (see the Code snippet export options: Generating client code | Postman Learning Center ) The login response includes your valid JWT { “access_token”: “<your JWT is here>” “token_type”: “Bearer”, “expires_in”: <expiration time in seconds> }
Aggregation endpoint: /aggregate/find?
Request to the aggregate endpoint return aggregations (sum or average) based on user specified groupings. This is accomplished via additional request parameters to specify the type of aggregation, the temporal window to aggregate by, and the metadata field name to group by. Unlike the detailed endpoint, which is updated on a rolling basis, the aggregate endpoint is updated once per week, Thursdays at 14:00 UTC, which is the associated reportTime for data being published in that reporting week. This is a two-dimensional aggregation, both spatial and temporal options are available. Request format (aggregate endpoint) The basic form for the aggregate request is: https://portal.ursaspace.com/api/data/aggregate/find?qry_<FieldName>=<Value>& qry_ReportTime_start=<timestamp>&qry_ReportTime_end=<timestamp>&grp_<Time window>=ReportTime&grp_ValueOf=<Group by field>&agg_<aggregation type> Again, this request should include an Authorization key in the header with the value Bearer <Your unique token>. Some useful aggregations may be to query at one aggregation level, such as Country (qry_Country=<some country>) and group at a more granular level (grp_ValueOf=LocationName). This allows your application to identify valid Locations within <some country>, in this example. Queries across multiple axes will attempt to AND the qry. For example, qry_LocationName=Cushing&qry_Country=China would look for tanks with location name of Cushing AND country name of China. Requests within the multiple values in the same axis will OR the values. So qry_LocationName=Cushing&qry_LocationName=Dalian would look for Cushing OR Dalian. If the request had multiple axes each with multiple values, the API will look for multiple combinations (an OR of ORs). For example, qry_LocationName=Cushing&qry_Country=China&qry_Country=United States&qry_LocationName=Dalian the API would look for multiple combinations. In this case tanks with location Cushing and country United States and the tanks with location Dalian and Country China would be included in the response. Tanks with location Cushing and country China would be returned too, but that combination of location and country is not present in the data and so no results will be returned for it. Response format (aggregate endpoint) This example shows a single result. More items would be appended to the groupAggregates array if more results are returned. { “queryRequestId”: “<GUID>”, “queryTime”: “<ISO 8601 Timestamp>”, “queryUrl”: “aggregate/find”, “queryParameters”: { “agg_<Aggregation type>”: [ “” ], “grp_<Time window>”: [ “ReportTime” ], “qry_ReportTime_end”: [ “<ISO 8601 Timestamp>” ], “qry_ReportTime_start”: [ “<ISO 8601 Timestamp>” ], “qry_<Field>”: [ “<Value>” ] }, “links”: {}, “queryResult”: { “appliedGroupByFunctions”: { “ReportTime”: “<Time window>_ReportTime” }, “appliedAggregateFunctions”: [ “<Aggregation type>” ], “groupAggregates”: [ { “coordinates”: { “<Time window>_ReportTime”: “<ISO 8601>” }, “values”: { “capacityBarrels_<Agg type>”: <value>, “fillBarrels_<Agg type>”: <value> } } ] } }
Detailed endpoint: /api/data/detailed/find?
Requests directed at the detailed endpoint will return tank by tank data. Request format (detailed endpoint) The basic form for the detailed request is: https://portal.ursaspace.com/api/data/detailed/find?qry_<FieldName>=<Value>&qry_<TimeField>_start=<timestamp>&qry_<TimeField>_end=<timestamp> Timestamp should take the form YYYY-MM-DDThh:mm:ssZ based on ISO 8601 standard. No quotes, single or double, are used around any values. Multiple qry_<FieldName>=<Value> pairs can be utilized by appending with an ampersand. A list of queryable fields and valid values is available later in this document. There are multiple time range options: ReportTime, PublishTime and ResultTime. Only once time range type can be queried on at a time, and the start date must be before the end date. See the data dictionary for time parameter definitions. To find the queryable values for a field with the API itself, try sending a request to the aggregate endpoint and grouping by the axis you are interested in. E.g., qry_SubscriptionType=China and grp_ValueOf=LocationName would show you all the valid LocationName values in China. Examples Query for all tank measurements with April report dates: https://portal.ursaspace.com/api/data/detailed/find?qry_ReportTime_start=2020-04-01T14:00:00.000Z&qry_ReportTime_end=2020-04-30T14:00:00.000Z Query for China tank measurements published between May 22, 2020 and May 23, 2020 https://portal.ursaspace.com/api/data/detailed/find?qry_PublishTime_start=2020-05-22T00:00:00.000Z&qry_PublishTime_end=2020-05-24T00:00:00.000Z&qry_Country=China Query for refinery tanks in Nigeria from Jan 1, 2020 to Feb 1, 2020 https://portal.ursaspace.com/api/data/detailed/find?qry_ReportTime_start=2020-01-01T00:00:00.000Z&qry_ReportTime_end=2020-02-01T00:00:00.000Z&qry_Country=Nigeria&qry_StorageType=Refinery Response format (detailed endpoint) { “queryRequestId”: “<GUID>”, “queryTime”: “<ISO 8601 Timestamp>”, “queryUrl”: “detailed/find”, “queryParameters”: { “qry_Country”: [ “<Country>” ], “qry_ReportTime_end”: [ “<ISO 8601 Timestamp>” ], “qry_ReportTime_start”: [ “<ISO 8601 Timestamp>” ]}, “links”: {}, “queryResult”: { “records”: [{ “tankEntityId”: null, “reportTime”: “2020-02-13T14:00:00.000Z”, “resultTime”: “2020-02-07T03:43:21.000Z”, “record”: { “coordinates”: { “axis_Algorithm”:”V3 Auto Sentinel”, “axis_Company”: “Baniyas Refining Company”, “axis_Country”: “Syria”, “axis_CrudeConfidence”: “Yes”, “axis_IsOecd”: “false”, “axis_LocationName”: “Baniyas”, “axis_Region”: “Middle East”, “axis_ReportTime”: “2020-02-13T14:00:00.000Z”, “axis_StorageType”: “Refinery”, “axis_SubscriptionType”: “All Regions,MENA”, “axis_TankEntity”: “BAN001”, “axis_TerminalName”: “SCOT (Baniyas)”, “axis_Territory”: “Tartus”, “axis_Sensor”: “HIMIAGE”, }, “values”: { “capacityBarrels”: 218594, “cylinderHeightM”: 17.7, “errorBarrels”: 832, “fillBarrels”: 66851, “heightDropM”: 12.287, “latitude”: 35.2189, “longitude”: 35.9657, “radiusAverageM”: 25 } } },}]}
Detailed Endpoint: Near Real Time Data Pull Update
As of Q2 2020, data is available via the detailed endpoint in “near real time”, meaning it is made available to users once it is processed and quality controlled in our system, rather than being available all at once at the reportDate time. The availability of data can be variable depending on when images are collected over given tanks and the speed of processing and quality assurance. This does not change the fundamental nature of the API (see example call above for detailed endpoint). This simply allows for some data to be accessible sooner than other data within a reporting window, which should be more convenient for the end user. Update: the ‘resultTime’ field is now queryable, similar to how a user would input qry_reportTime_start and qry_reportTime_end to access all tank measurements for a given period of time, based on reportDate. By using this field to query on, a user can get individual tank measurements for a given geospatial entity (e.g. country, terminal, location, etc.) within a more tightly defined time window if those measurements exist. An example is provided: https://portal.ursaspace.com/api/data/detailed/find?qry_Country=<Value>&qry_ResultTime_start=2020-02-06T14:00:00Z&qry_ResultTime_end=2020-02-08T14:00:00Z Output includes: { “tankEntityId”: null, “reportTime”: “2020-02-13T14:00:00.000Z”, “resultTime”: “2020-02-07T03:43:21.000Z”, “record”: { “coordinates”: { “axis_Company”: “Baniyas Refining Company”, “axis_Country”: “Syria”, “axis_CrudeConfidence”: “Yes”, “axis_IsOecd”: “false”, “axis_LocationName”: “Baniyas”, “axis_Region”: “Middle East”, “axis_ReportTime”: “2020-02-13T14:00:00.000Z”, “axis_StorageType”: “Refinery”, “axis_SubscriptionType”: “All Regions,MENA”, “axis_TankEntity”: “BAN001”, “axis_TerminalName”: “SCOT (Baniyas)”, “axis_Territory”: “Tartus” }, “values”: { “capacityBarrels”: 218594, “cylinderHeightM”: 17.7, “fillBarrels”: 66851, “heightDropM”: 12.287, “latitude”: 35.2189, “longitude”: 35.9657, “radiusAverageM”: 25 } } }, Some important things to keep in mind when using this update of the detailed endpoint going forward: Because data is made available as it is processed, queries can still return “records: []” in the middle of a reporting week for a given query. Data will come in periodically, so users may need to make consistent pulls in order to get updates in near real time. Ursa may publish partial results for a given geospatial entity (e.g. country, terminal, location) due to image coverage. Data will not be “carried forward” in the detailed endpoint, so users will need to account for this in processing and comprehension of data. An example to illustrate this concept is shown below: On February 9th, 2020, Sally uses the API to query for Zhoushan, China tank measurements from the last 3 days. She could use this API call: https://portal.ursaspace.com/api/data/detailed/find?qry_Location=Zhoushan&qry_ResultTime_start=2020-02-06T15:00:00Z&qry_ResultTime_end=2020-02-09T15:00:00Z She is aware that Ursa tracks ~144 million barrels of capacity in Zhoushan, China. She receives measurements from yesterday, but only sees results for a portion of the data – 98 million barrels of capacity. Sally is a bit confused – did these missing tanks go out of commission? Are they empty? No. It is likely that Ursa received an image that covered a portion of tanks only. After immediately processing and quality checking these results, these data are made available to the user. It is quite possible that the next day, the remaining tanks will receive a measurement that can be queried via the API – in order to complete a new measurement for the full set of tanks in Zhoushan. It is recommended that users of the updated detailed endpoint utilize data at the tank level. If a user requires the most recent total aggregate update for a given geospatial entity, the recommended courses of action are: Use the aggregate endpoint of the API, which is updated only at reportDate times. Perform queries in such a way that you receive the most recent measurement per tank in a set (likely done in code). Use the API to update another internal database where each measurement is added, then use any internal tools to aggregate these data however needed.
Update 2020: “Near Real Time” Detailed Endpoint Update FAQs
Q: Why has there been a change to the detailed endpoint? A: Ursa has updated processing capabilities in order to distribute data more quickly to customers. This data, provided at a tank-by-tank level, will be processed, quality-controlled, and delivered in a fluid manner in near real-time. Q: How do I use these changes? A: A user does not have to change anything about API calls made to the detailed endpoint. However, users should be expecting to see data made available in small increments, rather than one large publish on Thursdays at 14:00 UTC. Q: When will I receive my data? A: If you are receiving our weekly emailed reports or are accessing data via the user portal, nothing will change for you. The only feature that is being updated is the tank-by-tank (detailed) API endpoint. Data will come in as it is processed, pulled via our internal systems every 5 minutes. This means you could have new data made accessible quite often, but it will be up to you as a user to make a request for this data. Q: Is it true that I can receive only some tank measurements for a given location? A: Yes, this is the case via the updated detailed endpoint. If imagery captures half of a location, measurements will be made and provided, even if the full location has not been imaged yet. Missing data may be filled in soon after or at the time of report publishing (Thursday at 14:00 UTC). Q: Does this impact my use of the Ursa Portal? A: Not at all. The Portal uses the aggregate endpoint to populate itself, meaning that nothing at all will change for the Portal. Q: How should I be querying the data now? A: You can still use the ‘reportTime’ field to query for tank measurements, but now you can also use the ‘resultTime’ and ‘publishTime’ fields to access data. This means that you can query and receive measurements for any period you require. For example, you could utilize the API to get the most recent measurements for every tank globally, and then perform analytics on the data for more up-to-date intelligence. For reference, these three date fields can be defined as follows: resultTime = The moment in time the image was taken. publishTime = The moment in time the data was made available via API. reportTime = Thursdays at 14:00 UTC each week, a normalizing date to standardize measurements from a week. If there are any questions on these changes, examples, or you are having any problems, please contact us at support@ursaspace.com.
Aggregate and Detailed Endpoint Query Fields
Aggregation type (agg_<Aggregation type>) Sum Avg Query fields (qry_<FieldName>=<Value>) TankEntity ReportTime ResultTime PublishTime SubscriptionType Region Country Territory LocationName Company TerminalName CrudeConfidence StorageType Group by fields (grp_ValueOf=<Field name>) Country Region SubscriptionType Company LocationName Territory TerminalName StorageType Temporal Windows (grp_<Time Window>=ReportTime) None Weekly Monthly Quarterly Annual
Valid values for each query field are available upon request to: support@ursaspace.com Subject: Oil API
Detailed Response Value Definitions
PLATFORM_AUTHENTICATION
The following describes the token security used to access Ursa Space’s platform APIs.
Endpoints
URL: https://platform.ursaspace.com/api/pas/login Request Type: POST Headers: Content-type: application/x-www-form-urlencoded Form Parameters: grant_type: “password” username: <your username> password: <your password> Returns:
VEHICLE_COUNTING
The vehicle counting results are contained in a GeoJSON file as a FeatureCollection, with one Feature per vehicle lot. One file is generated per image, and that image which may contain several lots.
Sample output files available upon request.
Field Description
Each Feature in the FeatureCollection contains the following fields: type: always “Feature” geometry: defined as a standard GeoJSON Polygon geometry (with MultiPolygon type). properties: a dictionary with the fields described in the following table
Schema
VESSEL_DETECTION
This analytic detects vessels in SAR imagery and correlates them with AIS data to provide additional ship metadata.
The following files will be delivered for Vessel Detection:
port_vessel_detections.csv – A master CSV file containing vessel detections from SAR imagery as well as AIS-derived information if the vessel had its AIS on.
chip.png – A directory of PNG-format “chip” files. Each file represents one of the detections listed in the CSV file.
Sample output files available upon request.
port_vessel_detections.csv – A master CSV file containing vessel detections from SAR imagery as well as AIS-derived information if the vessel had its AIS on.
chip.png – A directory of PNG-format “chip” files. Each file represents one of the detections listed in the CSV file.
Summary Table of Output Files
Sample of port_vessel_detections.csv and chip.png files available upon request.
Data Dictionary
Delivery Information
How do I receive Vessel Detection data from Ursa? Data will be pushed to an Ursa-owned S3 bucket by our team of experts, based on your request. How will I be notified by data is available? When data is uploaded to the appropriate S3 bucket, you will be notified by an Ursa expert. How does QC work for Vessel Detection? Are the results reviewed before I receive them? Ursa’s Vessel Detection capability can be customized based on your needs. If high accuracy is crucial for you, we may suggest a human be in the loop to review algorithm outputs prior to your consumption. We will appropriately flag results from our platform for review by our team of experts before it is sent to you. If speed is of the essence for you, then we can program our system to send you the data as soon as it is available. In this case, we will still review results after the fact for quality assurance, but you will have access to the initial version immediately after production.
