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 SPOTLIGHT STRIPMAP 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 State Description created Product item has been created completed Product has been delivered successfully Delivery State Description creating Delivery item is being created delivered Delivery item is delivered and ready to be retrieved by the customerImaging 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 Field Name Type Description name string Name of the color coding for the blob polygon. A value of ‘red’ indicates the pixels in the earlier image had a stronger return than in the latest image (“red fled”). A value of ‘blue’ indicates that the pixels in the latest image had a stronger return than in the earlier image (“blue new”).
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 Field Name Type Description name string Name of the color coding for the blob polygon. A value of ‘red’ indicates the pixels in the earlier image had a stronger return than in the latest image (“red fled”). A value of ‘blue’ indicates that the pixels in the latest image had a stronger return than in the earlier image (“blue new”). area number Polygon area in square meters (calculated in EPSG:3857) max_intensity_of_change number The maximum pixel intensity value of the difference map for the pixels that constitute the change polygon. This is unnormalized and will be relative to the pair of images. min_intensity_of_change number The minimum pixel intensity value of the difference map for the pixels that constitute the change polygon. This is unnormalized and will be relative to the pair of images. mean_intensity_of_change number The mean pixel intensity value of the difference map for the pixels that constitute the change polygon. This is unnormalized and will be relative to the pair of images. total_intensity_of_change number Sum of the pixel intensity value across the difference map for the pixels that constitute the change polygon. max_strength_of_change number The difference between the polygon maximum intensity of change and the global mean of the difference map, divided by the global standard deviation of the difference map. min_strength_of_change number The difference between the polygon minimum intensity of change and the global mean of the difference map, divided by the global standard deviation of the difference map. mean_strength_of_change number The difference between the polygon mean intensity of change and the global mean of the difference map, divided by the global standard deviation of the difference map. normalized_change_prob number Mean strength of change transformed to percentiles in a normal distribution. Higher percentiles indicate a larger distance to the global mean of the difference map and higher confidence in the change polygon. normalized_change_prob_category string A human-readable categorization of the confidence in the change. Options include: ‘remote’, ‘highly_improbable’, ‘improbable’, ‘roughly_even_odds’, ‘probable’, ‘highly_probable’, ‘nearly_certain’ max_intensity_of_change_by_area number Maximum intensity of change divided by polygon area. min_intensity_of_change_by_area number Minimum intensity of change divided by polygon area. mean_intensity_of_change_by_area number Mean intensity of change divided by polygon area. total_intensity_of_change_by_area number Total intensity of change divided by polygon area. max_strength_of_change_by_area number Maximum strength of change divided by polygon area. min_strength_of_change_by_area number Minimum strength of change divided by polygon area. mean_strength_of_change_by_area number Mean strength of change divided by polygon area. centroid_latitude number Latitude value for the centroid of the change blob polygon. centroid_longitude number Longitude value for the centroid of the change blob polygon. polygon string Polygon vertices, provided in GeoJSON Polygon coordinates format referenceDate string Time and date of the reference image, e.g., ‘2021/10/06 11:53:58’ matchDate string Time and date of the match image, e.g., ‘2021/12/05 11:53:57’ reference_imageID string Reference image ID. Format is vendor-specific. match_imageID string Match image ID. Format is vendor-specific.
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: 1 { 2 ursa_udp_availablemetadatarecord(QUERYPARAMS) { 3 FIELDLIST 4 } 5 } Response Body: Content-type: application/json Information about order and current status Response JSON Data: SAR Image Catalog Response of the form: 1 { 2 “paginationInfo”: { 3 “nextOffset”: <int>, 4 “recordsInPage”: <int> 5 }, 6 “data”: { 7 “ursa_udp_availablemetadatarecord”: [ 8 { 9 // returned records 10 }, 11 { 12 // returned records 13 } 14 ] 15 } 16 } 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: 1 { 2 “paginationInfo”: { 3 “recordsInPage”:0 4 }, 5 “errors”: [ 6 { 7 “message”: “Invalid Syntax”, 8 “locations”: [{“line”:3,”column”:66}], 9 “errorType”: “InvalidSyntax”, 10 “extensions”: null, 11 “path”: null 12 } 13 ] 14 }
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” } } }
Operation | Operator |
---|---|
Equals | eq |
Not Equals | ne |
Greater Than | gt |
Less Than | lt |
Or | or (with square-bracketed [ ] input list) |
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:
1 | { |
2 | ursa_udp_availablemetadatarecord( |
3 | limit: 10 |
4 | content: { catalogProperties: { vendor: { eq: “ICEYE” } } } |
5 | ) { |
6 | assignedId |
7 | } |
8 | } |
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
1 | { |
2 | ursa_udp_availablemetadatarecord( |
3 | limit: 10 |
4 | sortBy: { |
5 | field: “content.catalogProperties.startTimeUTC”, |
6 | sortOrder: “ASC” |
7 | } |
8 | content: { catalogProperties: { vendor: { eq: “ICEYE” } } } |
9 | ) { |
10 | assignedId |
11 | content { |
12 | catalogProperties { |
13 | wktPolygon |
14 | vendor |
15 | startTimeUTC |
16 | passType |
17 | } |
18 | } |
19 | } |
20 | } |
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.:
1 | { |
2 | ursa_udp_availablemetadatarecord( |
3 | offset: 5001 |
4 | uploadTime: { gt: “2020-01-01T00:00:00Z” } |
5 | content: { catalogProperties: { vendor: { eq: “ICEYE” } } } |
6 | ) { |
7 | assignedId |
8 | uploadTime |
9 | } |
10 | } |
SAR Metadata Schema
1 ursa_udp_availablemetadatarecord 2 { 3 assignedId 4 uploadTime 5 header { 6 version 7 commonProperties { 8 sourceVendor 9 startTimeUTC 10 endTimeUTC 11 } 12 } 13 content { 14 version 15 catalogProperties { 16 quicklookUrl 17 wktPolygon 18 geoJsonPolygon { 19 type 20 coordinates 21 } 22 vendor 23 startTimeUTC 24 endTimeUTC 25 passType 26 acquisitionMode 27 incidence { 28 incidenceNearDegs 29 incidenceFarDegs 30 } 31 collectionPlatform 32 antennaPointing 33 } 34 } 35 }
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: Vendor Enumeration Description ICEYE ICEYE SourceMission Enumeration Description ICE ICEYE PassType Enumeration Description ASCENDING Ascending Pass DESCENDING Descending Pass AntennaPointing Enumeration Description LEFT Left-looking Antenna RIGHT Right-looking Antenna AcquisitionMode Enumeration Description ICE_SPOTLIGHT_HIGH ICEYE Spotlight High Acquisition Mode ICE_SPOTLIGHT ICEYE Spotlight Acquisition Mode ICE_STRIPMAP_HIGH ICEYE Stripmap High Acquisition Mode ICE_STRIPMAP ICEYE Stripmap Acquisition Mode ICE_TOPSAR ICEYE TopSAR Acquisition Mode
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: Data Type File Format FORMAT EXT SICD SICD SICD NITF GEC GeoTIFF GEC TIF GTC GeoTIFF GTC TIF POV GeoTIFF POV TIF XML Metadata XML SICD XML
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
Field Example Definition reportTime 2020-05-21T14:00:00.000Z Thursday report date resultTime 2020-05-14T00:10:12.000Z Date the image was taken for this measurement publishTime 2020-05-18T14:00:01.000Z Date this measurement was published axis_Algorithm V3 Auto Only Ursa algorithm used to measure this tank axis_CarryForward false Indicates if this measurement was carried forward from last week axis_Company Plains All American Pipeline LP Company that own the tank axis_Country United States Tank country axis_CrudeConfidence Yes Confidence that this is a crude tank. Values are Yes, Probable, Unconfirmed, No axis_FirstReportTime 2017-04-26T14:00:00.000Z Date Ursa started measuring this location axis_IsOecd true Indicates if the tank is an OECD tank axis_LocationName Cushing Tank location axis_PublishTime 2020-05-18T14:00:01.000Z Date this measurement was published axis_Region Americas Tank region axis_ReportTime 2020-05-21T14:00:00.000Z Thursday report date axis_Sensor HIMAGE Sensor mode of image used for this measurement axis_StorageType Non-Refinery The tank’s storage type. Values are Refinery, Non-Refinery, SPR, Commercial axis_SubscriptionType All Regions,North America Tanks subscriptions axis_TankEntity CUH001 Unique ID for tank axis_TerminalName Plains All American Pipeline, LP (Cushing) Tank terminal axis_Territory PADD 2 Tank territory capacityBarrels 271215 Tank capacity in number of barrels cylinderHeightM 14.1 Tank height in meters errorBarrels 9834 Fill error range in number of barrels fillBarrels 72264 Tank fill in number of barrels heightDropM 10.3431 Distance between tank rim and tank lid in meters latitude 35.9432 Tank latitude longitude -96.7488 Tank longitude radiusAverageM 31.2 Tank radius in meters
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: 1 { 2 “access_token”: “<TOKEN>”, 3 “token_type”: “Bearer”, 4 “expires_in”: 28800 5 }
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 Field Name Type Description GEOINT_ID string The unique identifier for the GEOINT source that is used to exploit objects of interest (e.g. ImageID from vendor) IMAGING_SYSTEM string The imaging system for the GEOINT Source (“SAR”) IDENTIFIER string The globally unique and persistent identifier of an analytic result. For example, the unique identifier for an observation record. CAR_COUNT int The number of cars in the car lot, expressed as a whole number. CREATED_BY string Unique ID of the observation process that created the observation. The relationship of an analytic result to the process step taken to create the result. e.g. UrsaSARCarCountingV0.0.2 OBS_CLASSIFICATION string Information about restriction(s) and/or security control(s) applicable to dissemination of data regarding the aggregate of variables based on source and intelligence recorded in the observation Standard portion marking conventions (e.g. U//FOUO) SOURCE_DATE string The Zulu date of the GEOINT source (acquisition time), e.g. 2022-01-18 SOURCE_TIME string The Zulu time (GMT) of the GEOINT source (acquisition time), e.g. 0134Z LATITUDE float Geometric representation of information about a feature that is modeled as a spatial point (decimal degrees) LONGITUDE float Geometric representation of information about a feature that is modeled as a spatial point (decimal degrees) OBS_CERTAINTY int The level of reliability and accuracy based on the aggregate of all variables within an observation An integer in a range of 1 to 10, with 10 indicating the highest confidence level, 1 the lowest level of confidence. (rarely, 0 has been used to mark “bad” results either from a blurry or failed image formation). PLANT_NAME string The name of the vehicle plant being observed LOT_NUMBER int The number of the lot where vehicles are being counted REVIEW_STATUS string The current status of the data review process indicating if the observation had quality control process applied to verify observation accuracy String (values either “not reviewed”, “under review”, or “accepted”).
Schema
1 { 2 “$schema”: “https://json-schema.org/draft/2019-09/schema”, 3 “$id”: “https://json-schema.org/draft/2019-09/output/schema”, 4 “description”: “Car counting schema for Customer deliveries”, 5 “type”: “object”, 6 “properties”: { 7 “type”: {“type”: “string”}, # “FeatureCollection” 8 “features”: { 9 “type”: “array”, 10 “items”: { 11 “type”: “object”, 12 “properties”: { 13 “type”: {“type”: “string”}, # “Feature” 14 “geometry”: { 15 “type”: “object”, 16 “properties”: { 17 “type”: {“type”: “string”}, # “Polygon” 18 “coordinates”: { 19 “type”: “array”, 20 “items”: { 21 “type”: “array”, 22 “items”: { 23 “type”: “array”, 24 “items”: { 25 “type”: “number”, 26 } 27 } 28 } 29 } 30 } 31 }, 32 “properties”: { 33 “type”: “object”, 34 “properties”: { 35 “GEOINT_ID”: {“type”: “string”}, 36 “IMAGING_SYSTEM”: {“type”: “string”}, 37 “IDENTIFIER”: {“type”: “string”}, 38 “CAR_COUNT”: {“type”: “number”}, 39 “CREATED_BY”: {“type”: “string”}, 40 “OBS_CLASSIFICATION”: {“type”: “string”}, 41 “SOURCE_DATE”: {“type”: “string”}, 42 “SOURCE_TIME”: {“type”: “string”}, 43 “LATITUDE”: {“type”: “number”}, 44 “LONGITUDE”: {“type”: “number”}, 45 “OBS_CERTAINTY”: {“type”: “number”}, 46 “PLANT_NAME”: {“type”: “string”}, 47 “LOT_NUMBER”: {“type”: “number”}, 48 “REVIEW_STATUS”: {“type”: “string”}, 49 } 50 } 51 } 52 } 53 } 54 } 55 }
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
File # File Name Extension Description 1 port_vessel_detections csv Final formatted vessel detection + AIS correlation file for customers 2 – X chips png Small images of each vessel detection (maps to ship_detections); X = Total number of detections from a given image – 1 Sample of port_vessel_detections.csv and chip.png files available upon request.
Data Dictionary
Column Name Example Description detect_uuid a26211aa-6bca-4cbf-9748-d08a485e5097 Unique, 16-digit row identifier image_timestamp 2021-09-01 12:34:56 The time the source image was taken (UTC) centroid_latitude 35.20868 Center latitude of the detected object centroid_longitude 129.5547 Center longitude of the detected object length 14.9992 Measured length of the detected object in meters width 14.7442 Measured width of the detected object in meters orientation 36.29461 (In degrees) The orientation from north speed 5.67 Estimated object speed (null for V1.0) conf_detect 0.573245 Confidence in the detection being a legitimate object (from 0 to 1) chip_identifier {“dataset”: “ursa_udp_tilerecord”, “blobRole”: “chip”, “assignedId”: “18af17b7-f05a-41cd-a18c-acbcc7dd6762”} Identification information so a user can pull a png “chip” file from the Ursa platform that corresponds with this detection record image_id 02210e31-2e65-4c14-8f51-24b6a8b200fa Unique Ursa image ID corresponding to the image used for this detection corr_confidence 90 The confidence in this detection being correlated to the associated AIS information (from 1 to 100) mmsi 636018728 MMSI value of the correlated vessel (via AIS) imo 1234567 IMO value of the correlated vessel (via AIS) length_ais 141.5 Length value of the correlated vessel in meters(via AIS) width_ais 65 Width value of the correlated vessel in meters (via AIS) name The Test Vessel The name of the correlated vessel (via AIS) flag US The country of origin/flag of the correlated vessel (via AIS) ship_type Oil Tanker The type of the correlated vessel (via AIS) ship_class Large Crude Oil Tanker The specific sub-type/classification of the correlated vessel (via AIS) callsign KX0983 The call sign of the correlated vessel (via AIS) draught 20 The draught of the correlated vessel in meters (via AIS) destination KYOTO The destination of the correlated vessel (via AIS) eta 2021-09-10 23:08:56 When the correlated vessel will arrive at the noted destination (via AIS) source_type AIS Secondary source of information (can potentially be replaced by RF, EO, etc.) area_of_interest Ulsan The Ursa defined port or area of interest associated with this detection report_date 2021-03-25 14:00:00 The normalized reporting date (weekly, Thursdays @ 14:00:00) to correlate to other Ursa datasets ais_correlation TRUE TRUE if this detection has a correlated vessel via AIS, FALSE if it does not
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.