Search the Archive Catalog API
A spec-compliant STAC API
The Archive Catalog contains a listing of thousands of SAR images available from Umbra. The Archive Catalog is a public (no authentication required!) read-only STAC API compliant with the v1.0.0 spec. Each STAC Item in the Archive Catalog represents an Umbra Collect.
Items tagged with umbra:open-data-catalog: true property are available in the Umbra Open Data Catalog hosted by AWS for free. See Search for Items in the Open Data Catalog below for details.
Searching the Archive Catalog
The Umbra Archive Catalog STAC API supports searching Items via the STAC Query and Filter Extensions.
Searching within a bounding box
A bounding box can be set to search for STAC Items within specific bounds. You can use https://geojson.io/ to mark out a bounding box. After drawing a shape on the map, go to Meta > Add bboxes to show the associated bounding box. Use this when constructing the query.
See the stac-api specification v1.0.0 for more information about basic search queries.
POST https://api.canopy.umbra.space/archive/search
content-type: application/json
{
"limit": 10,
"bbox": [
-119.8792576517811,
34.318681740683246,
-119.54554123766826,
34.503965775376656
]
}
Searching within a polygon
A GeoJSON polygon can be used for a more specific search area. Using https://geojson.io/ you can mark the area of interest and then copy the geometry into your query.
POST https://api.canopy.umbra.space/archive/search
content-type: application/json
{
"limit": 10,
"intersects": {
"coordinates": [
[
[
-120.12597936063744,
34.65814832293938
],
[
-120.12597936063744,
34.17447215802946
],
[
-119.37177594853814,
34.17447215802946
],
[
-119.37177594853814,
34.65814832293938
],
[
-120.12597936063744,
34.65814832293938
]
]
],
"type": "Polygon"
}
}
Searching by Date and Time
You can specify a datetime range using an RFC 3339 datetime interval. See the STAC API spec for more details.
POST https://api.canopy.umbra.space/archive/search
content-type: application/json
{
"limit": 10,
"datetime": "2023-10-20T00:00:00Z/2023-10-21T00:00:00Z"
}
Searching by Property
You can search by a property using CQL2 queries. Below searches for STAC Items where sar:resolution_range == 1.
See the stac-api filter extension specification for details about advanced search queries. More examples can be found in the cql2 schema examples repository.
POST https://api.canopy.umbra.space/archive/search
content-type: application/json
{
"limit": 10,
"filter-lang": "cql2-json",
"filter": {
"op": "=",
"args": [
{
"property": "sar:resolution_range"
},
1
]
}
}
Search by Collect ID
You can search for STAC Items associated with a collect ID. The order of arguments matters: needle (["29fb4e31-0879-4f1a-8b43-18f0200fe9d1"]) then haystack {"property": "umbra:collect_ids"}.
POST https://api.canopy.umbra.space/archive/search
content-type: application/json
{
"limit": 10,
"filter-lang": "cql2-json",
"filter": {
"op": "in",
"args": [
["29fb4e31-0879-4f1a-8b43-18f0200fe9d1"],
{
"property": "umbra:collect_ids"
}
]
}
}
Search for Items in the Open Data Catalog
The Archive Catalog uses the umbra:open-data-catalog: bool property to indicate whether a particular Item is in the Umbra Open Data Catalog on AWS. You can search for items matching this property with:
POST https://api.canopy.umbra.space/archive/search
content-type: application/json
{
"limit": 10,
"filter-lang": "cql2-json",
"filter": {
"op": "=",
"args": [
true,
{
"property": "umbra:open-data-catalog"
}
]
}
}
Like any other CQL2 query, this can be combined with other query parameters as shown in Complex Searches below.
Finding Data in the Umbra Open Data S3 Bucket
Unfortunately there is currently no direct link from the Archive Catalog Item to the file path in the Umbra Open Data AWS S3 bucket. We recommend dumping the s3 paths in that bucket and then searching through the file list by the umbra:task_id property for the desired Archive Catalog Item.
aws s3 ls --no-sign-request s3://umbra-open-data-catalog/ --recursive > umbra-open-data-catalog-list.txt
grep {umbra:task_id} umbra-open-data-catalog-list.txt
Complex Searches
Here is an example search for resolution range = 1, grazing_angle > 50, taken on October 20, 2023, and which is contained by a specific GeoJSON polygon.
POST https://api.canopy.umbra.space/archive/search
content-type: application/json
{
"limit": 10,
"filter-lang": "cql2-json",
"filter": {
"op": "and",
"args": [
{
"op": "=",
"args": [
{
"property": "sar:resolution_range"
},
1
]
},
{
"op": ">",
"args": [
{
"property": "umbra:grazing_angle_degrees"
},
50
]
}
]
},
"datetime": "2023-10-20T00:00:00Z/2023-10-21T00:00:00Z",
"intersects": {
"coordinates": [
[
[
-120.12597936063744,
34.65814832293938
],
[
-120.12597936063744,
34.17447215802946
],
[
-119.37177594853814,
34.17447215802946
],
[
-119.37177594853814,
34.65814832293938
],
[
-120.12597936063744,
34.65814832293938
]
]
],
"type": "Polygon"
}
}
Other Archive Catalog Queries
Retrieving a specific Archive Item
To retrieve a specific Archive STAC Item, append the Item's ID to the query. This operation might commonly be used to lookup a particular Collect in the Archive after retrieving associated Archive IDs from Collect.properties.archive_ids.
GET https://api.canopy.umbra.space/archive/collections/umbra-sar/items/{archive_id}
Listing Archive Items by Collection
All Items in the Archive are found in the umbra-sar collection. To retrieve a listing of items in our umbra-sar collection, use the following query.
GET https://api.canopy.umbra.space/archive/collections/umbra-sar/items
Retrieving a Preview Thumbnail for a specific Archive Item
Retrieve a preview thumbnail 512x512 png image for an Archive Item by querying the thumbnail endpoint:
GET https://api.canopy.umbra.space/archive/thumbnail/{archive_id}
Updated 3 months ago