Documentation

Your access to satellite imagery and analytic results
with no geographic, political, or weather-related limitations.

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

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>
The <TOKEN> is the access_token acquired from the login endpoint.
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	}

GraphQL Query Details

Query Parameters

Query Operators

Limiting Returned Data

Sorting Results

Pagination

Query Parameters

Query Operators

Operation	Operator
Equals	eq
Not Equals	ne
Greater Than	gt
Less Than	lt
Or	or (with square-bracketed [ ] input list)

Limiting Returned Data

Sorting Results

Pagination

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

IMAGERY_PRODUCT_DELIVERY

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

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

PLATFORM_AUTHENTICATION

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.

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.

Cookie	Duration	Description
cookielawinfo-checkbox-analytics	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional	11 months	The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
viewed_cookie_policy	11 months	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.

1	{
2	ursa_udp_availablemetadatarecord(
3	limit: 10
4	content: { catalogProperties: { vendor: { eq: “ICEYE” } } }
5	) {
6	assignedId
7	}
8	}

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	}

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	}

1	{
2	“access_token”: “<TOKEN>”,
3	“token_type”: “Bearer”,
4	“expires_in”: 28800
5	}

Company

Industries

News

Solutions

Your access to satellite imagery and analytic resultswith no geographic, political, or weather-related limitations.

BASIC_CHANGE_DETECTION

GeoJSON

GeoTIFF

CHANGE_INTENSITY_METRICS

GeoJSON

CSV

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

Accessing your Deliveries

How to Assume a Role in the AWS Web Console

IMAGERY_CATALOG_SEARCH

Endpoints

GraphQL Query Details

SAR Metadata Schema

SAR Catalog Enumerations

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 readyThe delivery will be available in an AWS S3 bucket owned by Ursa that has been configured prior to image delivery

Content of Delivery

IMAGERY_REQUEST_ORDER

PLATFORM_AUTHENTICATION

The following describes the token security used to access Ursa Space’s platform APIs.

Endpoints

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

Schema

VESSEL_DETECTION

Summary Table of Output Files

Data Dictionary

Delivery Information

Want to learn more about what Ursa has to offer?

Company

INDUSTRIES

News

SOLUTIONS

Company

Industries

News

Solutions

Your access to satellite imagery and analytic results
with no geographic, political, or weather-related limitations.

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

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.