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.
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.