Search the Archive Catalog API

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

📘
Authentication is currently required to access the Archive Catalog of all Umbra archived Collects.

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

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}