Search the Archive Catalog API

The Archive Catalog contains a listing of thousands of SAR images available from Umbra. The Archive Catalog is a read-only STAC API compliant with the v1.0.0 spec. Each STAC Item in the Archive Catalog represents an Umbra Collect. The Archive Catalog requires authentication to access.

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. Here are all of the supported properties for archive STAC items:

Property	Description
`id`	Unique id for STAC item
`created`	Timestamp when archive STAC item was created
`updated`	Timestamp when archive STAC item was updated
`datetime`	Timestamp for the collect (collection time)
`platform`	Satellite that captured the collect
`start_datetime`	Timestamp for when collection began
`end_datetime`	Timestamp for when collection ended
`sar:product_type`	Umbra product type (eg. "GEC")
`sar:looks_azimuth`	Number of looks in the azimuth dimension
`sar:polarizations`	Polarizations (typically `["VV"]` or `["HH"]`)
`sar:frequency_band`	Frequency band (typically `"X"`)
`sar:instrument_mode`	Instrument mode (`"SPOTLIGHT"` or `"SCAN"`)
`sar:resolution_range`	Range resolution in meters
`sar:resolution_azimuth`	Azimuth resolution in meters
`view:incidence_angle`	Incidence angle in degrees
`umbra:task_id`	Task id
`umbra:collect_ids`	Collect id(s)
`umbra:squint_angle_degrees`	Squint angle in degrees
`umbra:grazing_angle_degrees`	Grazing angle in degrees
`umbra:slant_range_kilometers`	Slant range in kilometers
`umbra:target_azimuth_angle_degrees`	Target azimuth angle in degrees
`umbra:squint_angle_engineering_degrees`	Engineering squint angle in degrees

The example below searches for STAC Items where the range resolution is 1 meter:

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
    ]
  }
}

See the stac-api filter extension specification for details about advanced search queries. More examples can be found in the cql2 schema examples repository.

Search by Collect ID

You can search for STAC Items associated with a collect ID:

POST https://api.canopy.umbra.space/archive/search
content-type: application/json

{
  "limit": 10,
  "filter-lang": "cql2-json",
  "filter": {
    "op": "a_overlaps",
    "args": [
      ["29fb4e31-0879-4f1a-8b43-18f0200fe9d1"],
      {
        "property": "umbra:collect_ids"
      }
    ]
  }
}

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}