Table of Contents
Summary
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.
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:
{
ursa_udp_availablemetadatarecord(QUERYPARAMS) {
FIELDLIST
}
}
Response Body:
-
Content-type: application/json
-
Information about order and current status
Response JSON Data:
SAR Image Catalog Response of the form:
{
“paginationInfo”: {
“nextOffset”: <int>,
“recordsInPage”: <int>
},
“data”: {
“ursa_udp_availablemetadatarecord”: [
{
// returned records
},
{
// returned records
}
]
}
}
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:
{
“paginationInfo”: {
“recordsInPage”:0
},
“errors”: [
{
“message”: “Invalid Syntax”,
“locations”: [{“line”:3,”column”:66}],
“errorType”: “InvalidSyntax”,
“extensions”: null,
“path”: null
}
]
}
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 December 1, the query params will be:
uploadTime: { gt: “2020-12-01T00:00:00Z” }
Note: All dates are UTC and in ISO-8601 format.
To query for records from a specific vendor:
content: { catalogProperties: { vendor: { eq: “EGEOS” } } }
Query Operators
|
Operation |
Operator |
|---|---|
|
Equals |
eq |
|
Not Equals |
ne |
|
Greater Than |
gt |
|
Less Than |
lt |
|
Or |
or (with square-bracketed [ ] input list) |
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, simply specify limit to specify the number of records to return. The following query returns 10 ICEYE SAR image catalog records:
{
ursa_udp_availablemetadatarecord(
limit: 10
content: { catalogProperties: { vendor: { eq: “ICEYE” } } }
) {
assignedId
}
}
Sorting Results
As part of the query parameters, you can specify a field to sort by. To sort records by a specific field, use the sortBy query parameter. The sortBy query “object” contains two fields:
- field: a dot-separated path to the field to sort by
- sortOrder: either ASC or DESC
{
ursa_udp_availablemetadatarecord(
limit: 10
sortBy: {
field: “content.catalogProperties.startTimeUTC”,
sortOrder: “ASC”
}
content: { catalogProperties: { vendor: { eq: “ICEYE” } } }
) {
assignedId
content {
catalogProperties {
wktPolygon
vendor
startTimeUTC
passType
}
}
}
}
Pagination
The query service returns a maximum of 5000 records in a single query and supports paging to retrieve datasets greater than 5000 records. When your dataset exceeds 5000 records, you can invoke the same query again but with an offset parameter, e.g.:
{
ursa_udp_availablemetadatarecord(
offset: 5001
uploadTime: { gt: “2020-01-01T00:00:00Z” }
content: { catalogProperties: { vendor: { eq: “ICEYE” } } }
) {
assignedId
uploadTime
}
}
SAR Metadata Schema
ursa_udp_availablemetadatarecord
{
assignedId
uploadTime
header {
version
commonProperties {
sourceVendor
startTimeUTC
endTimeUTC
}
}
content {
version
catalogProperties {
quicklookUrl
wktPolygon
geoJsonPolygon {
type
coordinates
}
vendor
startTimeUTC
endTimeUTC
passType
acquisitionMode
incidence {
incidenceNearDegs
incidenceFarDegs
}
collectionPlatform
antennaPointing
}
}
}
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 |