1. Info
  2. Global Monitoring Service

Getting Started with the Global Monitoring Service Using STAC

This guide will walk you through the full process of accessing Global Monitoring data via STAC compliant API endpoints

About the Global Monitoring Service

Ursa Space's Global Monitoring Service (GMS) offers near real-time insights derived from satellite imagery worldwide. By combining state-of-the-art image analysis algorithms with a network of commercial data providers, GMS enables decision-makers to identify vessels, ground vehicles, aircraft, man-made objects, and changes in the environment. This article focuses on accessing this information via STAC compliant API endpoints, but visual dashboards are also available for use.

If you are looking to download GMS detections using GraphQL endpoints then please refer to the documentation here

Performing Queries (POST /search)

All detections are stored in a SpatioTemporal Asset Catalog (STAC) that supports advanced geospatial querying. Time ranges, bounding polygons, field specific filters, and other parameters can be used to narrow down results to a select subset of interest. Details about each of these parameters can be found in the specification here: STAC API - Item Search. The search endpoint for Global Monitoring Service STAC can be found at the following URL:

https://platform.ursaspace.com/api/ars/search

Requests to this endpoint require authentication. Please see this article to learn how to generate bearer tokens. Once a token is generated, it must be included in the Authorization header of every request using the following format:

Authorization: Bearer <token>

The Global Monitoring Service offers a variety detection categories, each of which are available in their own dedicated STAC Collection(s):

  • Aircraft Detection (gms_aircraft_detection)
  • Ground Vehicle Detection (gms_ground_vehicle_detection)
  • Vessel Detection (gms_vessel_detection)
  • Object Detection (gms_object_detection)
  • MANmade Targets in SAR (MANTIS) (gms_mantis)
  • Change Detection (gms_change_detection)

Information about the satellite imagery used to derived each detection can be found in the gms_analytic_execution collection. Please see the "Accessing Sensor Data" section below for more details.

With this in mind, each individual detection is stored as a STAC Item within its corresponding collection. Below is an example STAC Item Search POST body that will return June 2024 vessel detections in the Black Sea:

{
    "limit": 5,
    "collections": [
        "gms_vessel_detection"
    ],
    "datetime": "2024-06-01T00:00:00Z/2024-06-30T23:59:59Z",
    "intersects": {
        "type": "Polygon",
        "coordinates": [[[25.051282903805145,47.24823970324286],[25.051282903805145,40.3281757019069],[42.88317022241165,40.3281757019069],[42.88317022241165,47.24823970324286],[25.051282903805145,47.24823970324286]]]
    }
}

The response conforms to the STAC Item Search specification. In this example, some properties have been left out for brevity.

{
  "type": "FeatureCollection",
    "features": [
        {
          "id": "d3e0b298-a5e5-4add-9830-085603e77c59",
          "type": "Feature",
            "collection": "gms_vessel_detection",
"geometry: <Geojson compliant Geometry Object>,
            "properties": {
              "datetime": "2024-06-22T04:23:26.404821Z",
                "processing:software": {
                    "Vessel Detection": "5.23.3"
                },
                "ursa:analytics:object_detection:width": 20.921896887637995,
                "ursa:analytics:object_detection:length": 27.90494431570141,
                "ursa:analytics:object_detection:heading": 10.672387905759393,
                "ursa:analytics:object_detection:confidence": 0.7028979663629029
          },
...please see the STAC Item specification for additional properties
      },
...
  ],
...please see the STAC Item Search specification for additional properties
}

Detection Item Properties (ursa:analytics:*) 

In addition to properties required by the STAC Item specification, each individual detection will contain a subset of the following properties within its properties field:

  • Aircraft detection items use ursa:analytics:classification:*
  • Ground vehicle detection items use ursa:analytics:classification:*
  • Vessel detection items use ursa:analytics:object_detection:*
  • Object detection items use ursa:analytics:object_detection:*
  • MANTIS detection items use ursa:analytics:object_detection:*
  • Change detection items use ursa:analytics:change_detection:*
Property Name Type Description
classification:category string Object category (e.g., Vehicle)
classification:type string Object type (e.g., Aircraft)
classification:subtype string Object subtype (e.g., Fixed-Wing aircraft)
classification:class string Object class (e.g., Bomber)
classification:model string Object model (e.g., H-6)
classification:confidence number Classification confidence, on a scale of 0 to 1
object_detection:length number Length of the object, in meters, as detected in the SAR imagery
object_detection:width number     Width of the object, in meters, as detected in the SAR imagery
object_detection:heading number Heading of the object, in degrees clockwise from true north, as detected in the SAR imagery
object_detection:confidence number Confidence that the detected object is an object of interest, on a scale of 0 to 1
change_detection:change_type string Type of change. Choices include: "arrival", "departure", "disturbed", "other", and "unknown".
change_detection:change_metric number The change statistic integrated over the change object’s area. Since the change statistic varies from 0 to 1, this change metric will always be less than the change object’s area.
change_detection:change_reference_datetime string Date/time of the last known pre-change image. For basic NCD, this will coincide with the reference image. For MT-NCD, this will be one of the images in the stack.
change_detection:change_datetime string Date/time of the earliest known post-change image. For basic NCD, this will coincide with the match image. For MT-NCD, this will be one of the images in the stack.

Each property name above has ursa:analytics as a prefix, but this has been excluded in the "Property Name" column to help with readability.

Accessing Sensor Data

Details about the underlying imagery consumed during analytical processing can be found in the gms_analytic_execution collection. Each item within this collection represents the execution of a particular analytic, and so it contains imagery details such as footprint, polarization, sensor mode, etc. As illustrated below, there is a one to many relationship between analytic execution items and detection items. 

Untitled

These relationships are encoded as bidirectional STAC-compliant Link Objects. Therefore, all child detections can be retrieved from the parent analytic execution item, and vise versa. The href of each link object takes the following format:

https://platform.ursaspace.com/api/ars/collections/{collection_name}/items/{item_id}

Here is an example link object that can be found in the links array of an analytic execution item

{
   "rel": "child",
"href": "https://platform.ursaspace.com/api/ars/collections/gms_mantis/items/e8f58740-7a64-4fac-8926-cb670fecd1f8",
  "type": "application/json"
}

Warning: There is no limit to the number of detections generated by a single analytic execution. We recommend using the ids parameter described in this table for downloading detections in bulk.

And here is an example link object that can be found in the links array of each detection item

{
"rel": "execution",
  "href": "https://platform.ursaspace.com/api/ars/collections/gms_analytic_execution/items/ed888ed2-a652-4158-9883-aa6a5bb4baf0",
  "type": "application/json"
}

Sensor Data Properties

In addition to properties required by the STAC Item specification, each analytic execution item will contain a subset of the following properties within its properties field:

Property Name Type Description
sensor_data:sensor_name string Sensor name
sensor_data:sensor_type string Sensor type, which may be one of: "SAR", "EO", "RF"
sensor_data:sensor_mode string Sensor mode, e.g. "Stripmap", "Spotlight", "Scan"
sensor_data:product_type string Product type, e.g. "SLC", "GRD", "GEC", "GTC"
sensor_data:ursa_id string Ursa internal image ID
sensor_data:vendor_id string Vendor specific product name
sensor_data:start_datetime datetime

Collection start time, described in ISO 8601 format

sensor_data:geometry_reference string WKT representing the geodetic coordinates of the location where the azimuth and incidence angles are specified
sensor_data:azimuth_angle number Angle from scene to sensor in degrees, clockwise relative to true North, defined at scene center
sensor_data:incidence_angle number Local incidence angle in degrees, defined at scene center
sensor_data:polarization string For SAR data, this is a two-character string indicating send and receive polarization. For RF data, this may be a single character indicating the receive polarization.
sensor_data:footprint string WKT describing the perimeter of the collection footprint, in WGS 84 coordinates

Each property name above has ursa:analytics as a prefix, but this has been excluded in the "Property Name" column to help with readability.