Global Monitoring Service API

Ursa Space's Global Monitoring Service API allows users to programmatically receive analytic results. Details below include token security and examples of querying using the GraphQL schema.

Table of Contents

Summary

Scope

• Features

API Endpoints

• Authentication
• GMS Results Query

GraphQL Query Results

• Query Parameters
• Query Operators
• Limiting Returned Data
• Pagination
• Sorting Results

Results Format

Vessel Detection Image Chips

Query Examples

• Query Based on Result Upload Time and Region
• Query for Specific Analytics in Specific Regions
• Query by Upload Time and Region, Return all Fields

Field Descriptions

• GMS Analytic Results Full Schema
• Top-level Field Definitions
• Content-level GeoJSON Field Definitions
• Product Field Definitions
• Processor Field Definitions
• SensorData Field Definitions
• Feature Field Defintions
• Dissemination Field Definitions

 

---

Summary

Ursa Space's Global Monitoring Service (GMS) is a more sensible way of retrieving data for vehicular detections, change detections and object detections. GMS is intended to improve upon these previous data sets and offer support for an increased amount of data. In addition, it provides a predictable cost and delivery time frame.

Currently, Ursa Space offers data for the Eastern Asian and Eastern European zones with future plans for additional regions. Analytic support is offered for small and large vessel detections, ground vehicle detections, aircraft detections, change detections, and man-made object detections.

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 is an available catalog of GMS results. Currently, the data pulls records from our GMS S3 bucket. Ursa Space catalogs all of these collections together in one central repository within the platform by normalizing the metadata fields into a single schema. This means users may query across the Virtual Constellation using the same criteria set without having to translate between different vendor formats.

 

---

Scope

This document describes the Global Monitoring Service API for programmatically retrieving GMS analytic results. It also describes the token security used to access the API and provides examples of querying using the GraphQL schema.

Code examples can be found in a Jupyter Notebook here: Ursa-GMS-API-Tutorial.ipynb

Features

• Query for analytic records in a region for a given time frame.
• Retrieve image chips for vessel detections in a specific area.

---

Endpoints: Authentication

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>

Response JSON Data:

{
    "access_token": "<TOKEN>",
    "token_type": "Bearer",
    "expires_in": 28800
}

Command Line Example

The following example assumes you have curl installed and available via your command line terminal. If you are new to curl or need help installing it on your machine, we recommend following an online guide such as https://developer.zendesk.com/documentation/api-basics/getting-started/installing-and-using-curl/ to get started.

export URSA_USERNAME=<your-username>
export URSA_PASSWORD=<your-password>
curl -X POST https://platform.ursaspace.com/api/pas/login \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=password&username=${URSA_USERNAME}&password=${URSA_PASSWORD}"

If the login was successful, you should get a text response in the Response JSON Data format above. Copy the <TOKEN> text out of the response and run the final command:

export TOKEN=<TOKEN>

This will create an environment variable $TOKEN that can be used in command line queries like those shown in Query Examples below.

---

Endpoints: GMS Results Query

The Ursa Space Global Monitoring Service results can be queried using GraphQL. With GraphQL, you specify both the fields you're querying on (specified as <QUERYPARAMS> below) as well as the fields you would like returned by the query (specified as <FIELDLIST> below).

URL: https://platform.ursaspace.com/api/psdm/graphql/gmss

Method: POST

Headers:

• Authorization: Bearer <TOKEN>
  The <TOKEN> is the access_token acquired from the login endpoint
• Content-Type: application/json

Request Body:

{
    ursa_udp_analyticgeojsonrecord(
        <QUERYPARAMS>
    ) {
        <FIELDLIST>
    }
}

Response Body:

{
   "paginationInfo": {
      "nextOffset": <int>,
      "recordsInPage": <int>
   },
   "data": {
     "ursa_udp_analyticgeojsonrecord": [
         {
           <record 1>
         },
         {
            <record 2>
         },
         ...
      ]
   }
}

The fields within the "returned records" objects are specified using the "<FIELDLIST>" in  your query. For more information on query parameters ("<QUERYPARAMS>" above) and possible returned fields, see the next sections.

 

---

GraphQL Query Details

Query Parameters

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 February 1, the query params will be:

uploadTime: { gt: "2023-02-01T00:00:00Z" }

Note: All dates are UTC and in ISO-8601 format.

To query for records from a specific region, e.g. "East Asia":

content: { processors: { parameters: { dissemination: { region: { 
    eq: "East Asia" 
} } } } }

To query for records over multiple regions, e.g. "East Asia" and "Eastern Europe":

content: { processors: { parameters: { dissemination: { region: {
    or: ["Eastern Europe", "East Asia"]
} } } } }

Note: we recommend GMS users always include at least one region in their query parameters. Due to data filtering based on user permissions, pages of results may be limited if this field is not included. By including this field with the query parameters, GMS users will always retrieve full pages of results in their responses.

All fields in the collection schema may be queried. For example queries and a full list of fields, see the sections below.

Query Operators

Note: The only field that does not use a query operator is assignedId.

Limiting Returned Data

As part of the query parameters, you can limit the number of records in a response.

In your query, set the limit field to specify the number of records to return. The following query returns 10 records:

{
    ursa_udp_analyticgeojsonrecord(
        limit: 10
        uploadTime: { gt: "2023-02-01T00:00:00Z" }
        content: { processors: { parameters: { dissemination: { region: { eq: "East Asia" } } } } }
    ) {
        assignedId
    }
}

Pagination

The query service returns a maximum of 5000 records in a single query and supports paging to retrieve datasets greater than 5000 records. If your response contains a nextOffset field under paginationInfo, then there are more records available in the next page. For example:

"paginationInfo": {
    "nextOffset": 5001,
    "recordsInPage": 5000
},

To access the next page, use the value from nextOffset in a field offset in a subsequent query. For example:

{
    ursa_udp_analyticgeojsonrecord(
        offset: 5001
        uploadTime: { gt: "2023-02-01T00:00:00Z" }
        content: { processors: { parameters: { dissemination: { region: { eq: "Eastern Europe" } } } } }
    ) {
        assignedId
    }
}

Sorting Results

As part of the query parameters, you can specify a field to sort by using the sortBy field.

The sortBy query "object" contains two fields:

• field: a dot-separated path to the field to sort by 

• sortOrder: Either ASC or DESC

For example, sorting by the collection start time:

{
    ursa_udp_analyticgeojsonrecord(
        sortBy: { 
            field: "content.sensorData.startTimeUTC", 
            sortOrder: "ASC" 
        }
        content: { 
            sensorData: { 
                startTimeUTC: {
                    gt: "2023-02-01T00:00:00Z"
                    lt: "2023-02-8T00:00:00Z"
                }
            }
            processors: { parameters: { dissemination: { region: { eq: "East Asia" } } } } 
        }
    ) {
        assignedId
        content {
            sensorData {
                sensorDataIndex
                sensorName
                startTimeUTC
                footprint
            }
        }
    }
}

 

---

Results Format

The response body returned by the GMS end is in the format:

{
   "paginationInfo": {
      "nextOffset": <int>,
      "recordsInPage": <int>
   },
   "data": {
     "ursa_udp_analyticgeojsonrecord": [
         {
           <record 1>
         },
         {
            <record 2>
         },
         ...
      ]
   }
}

Each record is in the format:

{
    "assignedId": "<UUID>",
    "uploadTime": "<ISO-8601_date>",
    "header": {
      ...

    },
    "content": {
       <valid-GeoJSON>
    }
}

header and content subfields are specified in the enumeration section below.

Note: values within the content field are valid GeoJSON and can be imported or overlayed with other GeoJSON libraries and software.

 

---

Vessel Detection Image Chips

Output from our Vessel Detection analytic include “image chips”, or small pieces of the original SAR image where a vessel was detected. These image chips are stored in S3 and can be retrieved with a simple recipe for generating the appropriate URL.

Consider the following trimmed-down record contained in a response from a GMS query returning a Vessel Detection result:

{
    "assignedId": "f8557ece-1048-4f01-aa90-471bf9835d8d",
    "uploadTime": "2023-02-02T00:04:32.667Z",
    "content": {
        "type": "FeatureCollection",
        "processors": [{
            "processorName": "Vessel Detection",
            "parameters": {
                "dissemination": {
                    "region": "Eastern Europe"
                },
                ...
            }
        }],
        "features": [{
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "sarChipIdentifier": "06810e9f836db9732be28326bcb1a4f1",
                ...
            }
        },
        ...
        ]
    }
}

To retrieve a PNG image for the 06810e9f836db9732be28326bcb1a4f1 chip, use the following:

https://gmss-public-images.s3.amazonaws.com/{region}/{sarChipIdentifier}.png

Replace the spaces (" ") in region with hyphens ("-"). For example, the above record produces the following URL:

https://gmss-public-images.s3.amazonaws.com/Eastern-Europe/06810e9f836db9732be28326bcb1a4f1.png

Please note that due to timing issues, some image chips may be missing from the S3 bucket. If you need an image chip that is being returned by the API, but is not present in the S3 bucket, please contact us at info@ursaspace.com.

 

---

Query Examples

The following command line query examples assume you have curl installed and available via your command line terminal. If you are new to curl or need help installing it on your machine, we recommend following an online guide such as https://developer.zendesk.com/documentation/api-basics/getting-started/installing-and-using-curl/ to get started.

Additionally, they assume you have an environment variable called TOKEN that you have set by following the instructions in the Authentication Command Line Example above.

Note that this is a RESTful API that can be queried using any number of tools or programming languages, such as Postman or Python's requests library. We are showing command line examples using curl here for simplicity.

Query Based on Result Upload Time and Region

The following command queries the GMS results database for results in East Asia that have been added since February 01, 2023, and limits the response to 10 results. The query returns a subset of available fields: assignedId, uploadTime, processorName (which analytic was run), parameters (inputs to the analytic that was run), and features (GeoJSON feature objects containing results from the analytic).

curl -H "Content-type: application/json" -H "Authorization: Bearer $TOKEN" \
  https://platform.ursaspace.com/api/psdm/graphql/gmss \
  -d '{
    ursa_udp_analyticgeojsonrecord(
        limit: 10
        uploadTime: {
            gt: "2023-02-01T00:00:00.000",
        }
        content: {
            processors: {
                parameters: {
                    dissemination: {
                        region: {
                            eq: "East Asia"
                        }
                    }
                }
            }   
        }
    )
    {
        assignedId
        uploadTime
        content {
            type
            processors {
                processorName
                parameters
            }
            features {
                type
                geometry {
                    type
                    coordinates
                }
                properties
            }
        }
    }
}'

Notes:

• A colon is used in the query parameters but not when listing returned data fields.
• "Compound" fields, such as features must include the subfields that you want returned. You cannot simply list features and get all of the items in that object.
• Whitespace is irrelevant

Query for Specific Analytics in Specific Regions

The following command queries for results from the "Change Detection" and "Vessel Detection" analytics, run in the GMS regions of "Eastern Europe" and "East Asia":

curl -H "Content-type: application/json" -H "Authorization: Bearer $TOKEN" \
  https://platform.ursaspace.com/api/psdm/graphql/gmss \
  -d '{
    ursa_udp_analyticgeojsonrecord(
        limit: 10
        content: {
            processors: {
                processorName: {
                    or: ["Change Detection", "Vessel Detection"]
                }
                parameters: {
                    dissemination: {
                        region: {
                            or: ["Eastern Europe", "East Asia"]
                        }
                    }
                }
            }
        }
    )
    {
        assignedId
        uploadTime
        content {
            type
            processors {
                processorName
                parameters
            }
            features {
                type
                geometry {
                    type
                    coordinates
                }
                properties
            }
        }
    }
}'

Query by Upload Time and Region, Return All Fields

curl -H "Content-type: application/json" -H "Authorization: Bearer $TOKEN" \
  https://platform.ursaspace.com/api/psdm/graphql/gmss \
  -d '{
    ursa_udp_analyticgeojsonrecord(
        uploadTime: {
            gt: "2023-02-01T00:00:00.000",
            lt: "2023-03-01T00:00:00.000"
        }
        content: { 
            processors: { 
                parameters: { 
                    dissemination: { 
                        region: { 
                            eq: "East Asia" 
                        }
                    }
                }
            }
        }
    )
    {
        assignedId
        uploadTime
        header {
            version
            generatorInfo {
                id
                timeUTC
                generatorType
                generatorVersion
            }
        }
        content {
            type
            product {
                productType
                documentVersion
            }
            processors {
                processorName
                version
                parameters
            }
            sensorData {
                sensorDataIndex
                sensorName
                sensorType
                sensorMode
                productType
                startTimeUTC
                geometryReference
                azimuthAngle
                incidenceAngle
                polarization
                footprint
                vendorId
                ursaId
            }
            features {
                type
                geometry {
                    type
                    coordinates
                }
                properties
            }
        }
    }
}'

 

---

Field Descriptions

GMS Analytic Results Full Schema

ursa_udp_analyticgeojsonrecord
    {
        assignedId
        uploadTime
        header {
            version
            generatorInfo {
                id
                timeUTC
                generatorType
                generatorVersion
            }
        }
        content {
            type
            product {
                productType
                documentVersion
            }
            processors {
                processorName
                version
                parameters
            }
            sensorData {
                sensorDataIndex
                sensorName
                sensorType
                sensorMode
                productType
                startTimeUTC
                geometryReference
                azimuthAngle
                incidenceAngle
                polarization
                footprint
                vendorId
                ursaId
            }
            features {
                type
                geometry {
                    type
                    coordinates
                }
                properties
            }
        }
    }

Top-level Field Definitions

Content-level GeoJSON Field Definitions

Product Field Definitions

Processor Field Definitions

The processor member of the FeatureCollection should be a list with one or more members representing each of the analytics that comprise the workflow.

SensorData Field Definitions

Sensor data for the image that was processed to generate the analytic results.

Feature Field Definitions

Dissemination Field Definitions