Analytics Ordering API

Ursa Space's Analytics Ordering API allows users to programmatically place requests for analytics to be run on their area of interest (AOI).

Table of Contents

Summary

• Detection Types
• Endpoints Overview
• Benefits

Scope

• Features

Initial Setup

Workflow Overview

API Error Codes

API Endpoints

• Generate a JSON Web Token (JWT)
• Place an Analytic Order
• Get Order Status
• Get All User Orders
• Get Order Request

Enumerations

• Analytic Offerings
• Order StatusHistory States

Summary

Place orders for custom-defined areas of interest and time ranges, available to limited users. 

Detection types:

With Ursa's Analytic Ordering API customers can currently order analyses on:

• Vessels near ports and in the open ocean (counted and possibly identified)
• Monitored populated regions (millimeter scale land subsidence and uplift)
• Aircraft in airdromes (counted and possibly identified)
• Man-made objects in a cluster
• Cars in commercial parking lots (counted) and stationary vehicles within an area of interest
• Very subtle object change detections between before-and-after images, such as vegetation growth or earth alterations due to vehicular tracks
• Medium-sized object change detections between before-and-after images, such as building construction and vehicular arrivals/departures in a scene

Endpoints

Possible endpoints include:

• Placing an order given an area of interest
• Getting the status for a specific order (associated with an ID) or for all orders associated with a user
• Getting the order request that was sent to Ursa Space (the same information used when a user places an order).

Benefits

Access to this ordering interface simplifies vendor relationships and orchestration for the user, which are formerly necessary steps to obtain analytics data inputs. With additional analytics scheduled for upcoming releases, this API makes Ursa Space’s world class catalog of analytics capabilities available to users programmatically, thus reducing ordering, processing, and delivery timelines.

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.

Back to Table of Contents

Scope

This document describes the API and service endpoints which will allow external Ursa Space users to programmatically order analytics over customer-defined areas of interest and time ranges. It also describes the token security used to access the API and provides examples for each request. A simple workflow from placing an order to receiving results is described below.

Features

• Order analytics to be run over a given area of interest (AOI) for a given time frame, past or future.
• Currently offering support for small and large vessel detections, subsidence monitoring, aircraft detections, man-made object detections, car counting, ground vehicle detections, and subtle/standard-sized change detections between a single pair or multiple pairs of images. Additional analytics are continuously added to the list.
• Check order status via endpoint requests and receive notifications via email when the order is created and when results are delivered.
• All results are delivered by API, but can also be securely replicated into a customer-defined S3 bucket.

Back to Table of Contents

Initial Setup

As this offering is currently only being offered to our Alpha customers, there is some initial setup that has to happen before placing an order. Namely, two steps need to take place:

• An S3 bucket with replication needs to be configured with Ursa’s IT department, which will be used to deliver results. In short, Ursa will drop results into an S3 bucket within Ursa’s domain and those results will be automatically replicated in the customer’s S3 bucket. This configuration provides a secure way to transfer sensitive information between domains. See https://aws.amazon.com/s3/features/replication/ for more details.
• User accounts will need to be generated for all members expecting to use the API.

Please contact support@ursaspace.com for generating accounts and to schedule an S3 bucket configuration.

Back to Table of Contents

Workflow Overview

This section provides a high-level overview of the steps involved in purchasing analytics from the Analytics Ordering API endpoints. More detail about each endpoint is provided below. Each endpoint is available at the domain https://platform.ursaspace.com/api.

1. Generate a JSON Web Token (JWT) through the POST /pas/login endpoint.
2. Place an analytic order through the POST /ios/order endpoint.
   1. Upon success, the response will include an orderId as well as information about the order itself.
   2. A confirmation email will also be sent to the contactEmail provided in the request.
3. Order status and other order information is retrieved from the GET /ios/order/{orderId} endpoint.
   1. 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.
4. At any time, users can retrieve all orders associated with their account via the GET /ios/order endpoint.
5. When the order is complete and analytic results are available for retrieval, an email will be sent to the email specified in the contactEmail of the initial order request.

Back to Table of Contents

API Error Codes

400 Bad Request

The request body has invalid information that cannot be processed.

401 Unauthorized

The request does not include valid authentication credentials.

403 Forbidden

The requesting user does not have access to the requested content.

404 Not Found

The requested resource (e.g. order) cannot be found.

405 Method Not Allowed

The request method is not valid for the endpoint, e.g. a POST is being used on a GET endpoint.

500 Internal Server Error

An error occurred during the endpoint’s execution.

Back to Table of Contents

Endpoints: Generate a JSON Web Token (JWT)

This endpoint enables users to generate a JSON Web Token (JWT) to support authentication for all the endpoints discussed below.

In the response body:

• The access_token field returned in the response body is a valid bearer token to authenticate subsequent requests.
• The expires_in field is the token longevity in seconds

Method: POST

Path: /pas/login

Form Parameters:

• grant_type: “password”
  
• username: <your username>
• password: <your password>

Response Code: 200: Credentials accepted

Response Body:

{
    "access_token": "string",
    "token_type": "Bearer",
    "expires_in": 28800
}

Back to Table of Contents

Endpoints: Place an Analytic Order

This endpoint enables authorized users to place an order for one or more analytics to be run on an image captured in a given time range and covering a given area of interest (AOI).

In the request body:

• The type field is a required field and must have the value workflow for analytic 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.
• The workflowRequest field must be of type “analytic”. This type contains a subfield “analytics”, which is a list containing all analytics requesting to be run.
  • See the Analytics enumeration at the end of this document for all analytics available for purchase. The list of available analytics will grow as we make more Ursa analytic algorithms available to customers.
• The schedule field currently must be of type “range”. This type contains a subfield range with subfields min and max. min and max values are in the ISO 8601 format.
  • The date range may be in the past or the future.
• The aois field is a list of AOIs you would like covered by your analytic. There are two types of allowable AOIs:
  • An AOI with the type field of “point” takes additional fields latitude_deg, longitude_deg, and radius_km.
  • An AOI with the type field of “polygon” takes one additional field geojson. The geojson is required to be a GeoJSON formatted JSON object of type “Polygon”. See the example request below or https://www.rfc-editor.org/rfc/rfc7946#section-3.1.6 for more details.
• The optional changeDetAnalyticParams field is used when a Change Detection analytic is ordered.
  • The changeDetectionType parameter specifies which change detection analytic is desired. The field must be one of the following types:
    • "CHANGE_DETECTION", "PORT_TRAFFIC", "PARKING_LOT", "CONSTRUCTION", "HURRICANE_DAMAGE", "LARGE_EARTH", or "OBJECT_LEVEL".
  • The maxImageWindowHrs parameter sets the maximum window in hours that the analytic will use for pulling images. This window is based on the time set in the schedule field and will go X hours before and X hours after the schedule range.
  • The recurringOrderParams field is an optional field that can be populated when ordering a change detection analytic.
    • The bounds field currently must be of type "range". This type containts both a min and a max subfield. min and max values are in ISO 8601 format.
    • The count field specifies how many recurring analytics should be scheduled.
    • The time field specifies an approximate time of day to try to pull images. It supports "morning", "evening" or "anytime".
    • The cadence field specifies how often the recurring order should run. It supports "daily", "weekly", "monthly" or "quarterly".
    • The minimumDaysBetweenImages field specifies a minimum window between recurring analytics. 

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 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).
• The products field refers to the deliverable products attached to that specific order. For the purposes of this API, this field can be ignored.

Method: POST

Path: /ios/order

EXAMPLE REQUEST BODY WITH POLYGON AOI:

{
  "descriptiveName": "Polygon AOI with multiple analytics",
  "purchaseReason": "An example of an order.",
  "customerNotes": "An example of an order with multiple analytics in a polygon",
  "request": {
    "type": "workflow",
    "contactEmail": "user@example.com",
    "workflowRequest": {
      "type": "analytic",
      "analytics": [
        "SmallVesselDetection", "LargeVesselDetection", "SubsidenceMonitoring", "AircraftDetection", "SPEX", "CarCounting", "GroundVehicleDetection"
      ]
    },
    "schedule": [{
        "type": "range",
        "range": {
          "min": "2022-03-03T14:00:00.000Z",
          "max": "2022-03-04T14:00:00.000Z"
        }
    }],
    "aois": [{
        "type": "polygon",
        "geojson": {
          "type": "Polygon",
          "coordinates": [[
              [-76.523,  42.452],
              [-76.488,  42.455],
              [-76.481,42.421],
              [-76.521,42.420],
              [-76.523,42.452]
          ]]
        }
    }]
  }
}

EXAMPLE REQUEST BODY WITH POINT AOI:

{
  "descriptiveName": "Point AOI with multiple analytics",
  "purchaseReason": "An example of an order.",
  "customerNotes": "An example of an order with multiple analytics in a point AOI.",
  "request": {
    "type": "workflow",
    "contactEmail": "user@example.com",
    "workflowRequest": {
      "type": "analytic",
      "analytics": [
        "SmallVesselDetection", "LargeVesselDetection", "SubsidenceMonitoring", "AircraftDetection", "SPEX", "CarCounting", "GroundVehicleDetection"
      ]
    },
    "schedule": [
      {
        "type": "range",
        "range": {
          "min": "2022-03-03T14:00:00.000Z",
          "max": "2022-03-04T14:00:00.000Z"
        }
      }
    ],
    "aois": [
      {
        "type": "point",
        "latitude_deg": 42.440550,
        "longitude_deg": -76.495690,
        "radius_km": 5
      }
    ]
  }
}

{
  "descriptiveName": "CCD with one analytic",
  "purchaseReason": "An example of an order.",
  "customerNotes": "An example of the coherent change detection with a single analytic in a single order.",
  "request": {
    "type": "workflow",
    "contactEmail": "user@example.com",
    "workflowRequest": {
      "type": "analytic",
      "analytics": ["ChangeDetection"]
    },
    "schedule": [{
        "type": "range",
        "range": {
          "min": "2022-03-03T14:00:00.000Z",
          "max": "2022-03-04T14:00:00.000Z"
        }
    }],
    "aois": [{
        "type": "polygon",
        "geojson": {
          "type": "Polygon",
          "coordinates": [[
              [-76.523, 42.452],
              [-76.488, 42.455],
              [-76.481, 42.421],
              [-76.521, 42.420],
              [-76.523, 42.452]
          ]]
        }
    }],
    "changeDetParameters": {
      "changeDetectionType": ["PORT_TRAFFIC"],
      "maxImageWindowHrs": 24,
      "recurringOrderParams": {
        "bounds": {
          "min": "2022-03-03T14:00:00.000Z",
          "max": "2022-03-04T14:00:00.000Z"
        },
        "count": 1,
        "time": "any",
        "cadence": "weekly",
        "minimumDaysBetweenImages": 2
      }
    }
  }
}

{
  "descriptiveName": "NCD with multiple analytics",
  "purchaseReason": "An example of an order.",
  "customerNotes": "An example of the non-coherent change detection with multiple analytics in a single order.",
  "request": {
    "type": "workflow",
    "contactEmail": "user@example.com",
    "workflowRequest": {
      "type": "analytic",
      "analytics": ["ChangeDetection"]
    },
    "schedule": [{
        "type": "range",
        "range": {
          "min": "2023-03-12T00:01:00.000Z",
          "max": "2023-03-12T23:59:00.000Z"
        }
    }],
    "aois": [{
      "type": "polygon",
      "geojson": {
        "type": "Polygon",
        "coordinates": [
          [
            [-76.523, 42.452],
            [-76.488, 42.455],
            [-76.481, 42.421],
            [-76.521, 42.420],
            [-76.523, 42.452]
          ]]
      }
    }],
    "changeDetAnalyticParams": {
      "changeDetectionType": ["PORT_TRAFFIC","PARKING_LOT"],
      "maxImageWindowHrs": 24
    }
  }
}

{
    "id": "1234-5678-9012",
    "descriptiveName": "An example of an order.",
    "purchaseReason": "string",
    "customerNotes": "An example response of an order request.",
    "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": "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": "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-12T14:51:52.443Z"
            }
        ]
    }
]