Guides
Open Canopy AppUmbra.Space

Migrate to STAC API v2

Suggest Edits

Users are strongly encouraged to migrate to STAC API v2 since the original STAC API is deprecated and will be discontinued in the near future.

Note that STAC API v2 is fully compliant with stac-spec v1.0.0.

How to Migrate

Use the Collects API for retrieving Umbra-specific metadata, including collect lifecycle information like status/status history.

Use STAC API v2 to search and retrieve assets and metadata.

Breaking Changes

URL

The STAC API v2 base URL includes a /v2 prefix.

https://api.canopy.umbra.space/stac/ (DEPRECATED)

becomes

https://api.canopy.umbra.space/v2/stac/

Endpoints

⚠️

Collection ID Change

The collection id is no longer the organization id. All items are now listed under a single collection id of umbra-sar.

⚠️

Item ID Change

The Item ID is no longer the Collect ID. It is a new Item ID to allow for a single Collect to be referenced by multiple Items in the STAC API.

See the "Get Assets for a Collect by Collect ID" Example below.

The API paths are consistent between versions in accordance with the the STAC API specification.

For v2, fetching collect items follows a familiar path pattern of /collections/{collection_id}/items/{item_id} however the collection id for v2 is always umbra-sar, giving a path of:

/collections/umbra-sar/items/{item_id}

Simple and advanced searching continues to be available via the /search endpoint using CQL2.

Please see the STAC API v2 reference for more details.

Metadata

STAC item metadata has changed to remove Umbra-specific metadata now available via the Collects API.

Fields added:

  • start_datetime
  • end_datetime
  • sar:frequency_band

Fields renamed:

  • umbra:grazing_angle → umbra:grazing_angle_degrees
  • umbra:squint_angle → umbra:squint_angle_degrees
  • umbra:target_azimuth_angle → umbra:target_azimuth_angle_degrees

Field removed:

  • umbra:auxiliary_properties
  • umbra:ipr
  • umbra:status
  • umbra:status_history
  • umbra:target_ipr
  • umbra:task_name
  • umbra:user_email
  • umbra:user_id
  • umbra:vehicle_id

📘

Resolution

Note that the target_ipr and ipr fields are functionally replaced by sar:range_resolution and sar:azimuth_resolution, respectively.

All four fields were present in the previous version of STAC API whereas in STAC API v2 only sar:range_resolution and sar:azimuth_resolution are present.

Examples

Get STAC Item by ID

A GET request for a STAC item with an id of d395379e-5184-4aaa-9300-2a9725c593f3 might looks like this:

curl 'https://api.canopy.umbra.space/v2/stac/collections/umbra-sar/items/d395379e-5184-4aaa-9300-2a9725c593f3'
  -H 'authorization: Bearer <token>'

The properties object in the STAC item JSON response should contain an umbra:collect_id field that can then be used to fetch a collect.

Here is an example of a STAC item properties object that might be returned:

{
  "id": "d395379e-5184-4aaa-9300-2a9725c593f3",
  "created": "2024-03-12T20:04:34.922116+00:00",
  "updated": "2024-03-12T20:04:34.922126+00:00",
  "datetime": "2024-03-13T08:22:19.379609+00:00",
  "platform": "Umbra-04",
  "end_datetime": "2024-03-13T08:22:20.295710+00:00",
  "umbra:task_id": "dad4f93f-071d-4ec1-a244-8168e91b997c",
  "start_datetime": "2024-03-13T08:22:18.463509+00:00",
  "sar:looks_range": 1,
  "sar:product_type": "GEC",
  "umbra:collect_id": "682a9306-c72b-4b77-a656-d33031a0d8d2",
  "sar:looks_azimuth": 1,
  "sar:polarizations": [
    "VV"
  ],
  "sar:frequency_band": "X",
  "sar:instrument_mode": "SPOTLIGHT",
  "sar:resolution_range": 1,
  "view:incidence_angle": 39.724300384521484,
  "umbra:organization_id": "org_OPKOgEGORTS4AlfT",
  "sar:resolution_azimuth": 1,
  "umbra:squint_angle_degrees": 44.93043899536133,
  "umbra:grazing_angle_degrees": 50.275699615478516,
  "umbra:slant_range_kilometers": 613.1199340820312,
  "umbra:target_azimuth_angle_degrees": 214.4052734375
}

With that umbra:collect_id of 682a9306-c72b-4b77-a656-d33031a0d8d2, we can make a request for that collect's information like so:

curl 'https://api.canopy.umbra.space/tasking/collects/682a9306-c72b-4b77-a656-d33031a0d8d2'
  -H 'authorization: Bearer <token>'

Get Assets for a Collect by Collect ID

If you want to go in the other direction — you have a collect id and want the STAC item to get the asset download links — you can POST to the search endpoint like so:

curl -H 'Content-Type: application/json' \
      -d '{
            "filter-lang": "cql2-json", 
            "filter": { 
              "op": "=", 
                "args": [ 
                  { "property": "umbra:collect_id" }, 
                  "06280b3f-0114-4c41-8381-c63a4b6b7a98" 
                ]
            }
          }' \
      -H 'authorization: Bearer <token>' \
      -X POST \
       'https://api.canopy.umbra.space/v2/stac/search'

Note that as of STAC API v2 you are no longer required to make requests to a separate endpoint to get signed URLs, provided that the result set is small (currently set to 5 items or less), since signed URLs are automatically returned when searching or fetching specific STAC items.

Here is an example of what the assets object may look like (note the alternate property with the signed URL already included):

{
  "2022-10-29-05-34-18_UMBRA-03.tif": {
    "alternate": {
      "s3_signed": {
        "description": "Expires at: 2024-03-13T16:27:03+00:00",
        "href": "https://dev-test-processed-sar-data.s3.amazonaws.com/2023-06-20/d41a5f76-86e0-4e33-972f-9fa36ac5d0eb/2022-10-29-05-34-18_UMBRA-03.tif?AWSAccessKeyId=ASIAZUHGNVNLFSHTWTOP&Signature=Azaey8PcoS0kxZn6xuIjZ65vmI0%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEFgaCXVzLXdlc3QtMiJHMEUCIQCEU%2B2RbtpxohZXWMi%2Bc46rMk9%2F4WjQQU9zVHlK34MadgIgSRS6%2FbAoARupxYmvs3mi9S61gIxwCzRT38A%2F2Wd%2FWIsq%2FAQIYRACGgw2NjE5MDgyMDQzNzQiDL8hXRWxKVrkuRHxlCrZBEn6osiQg%2Fv4rz%2B1OpbhcoQJW0q%2BVgmXLuKuaNOMejPUe4OjBUThiC7WVQN6Wei3vfwnJGpVEj%2BLC22BO1PYrUqXGUN6uyqpl%2FoRvLx11Q3ymuQknvxg4FjZsbyDmEfttjkeQ7ldWQiw%2FcAkCEEfSU2tNxKEU4UZvBiVl3hkQDnw566%2FiS9p7hEjbR0geuSyLNSaGye11lR1Tlc1lAH9SxzfO6DUv%2FSbOk%2B%2BaLZuTVDMEBErSCN0URFvkePU8DD5wkec1Y%2BD6cjUwdSdJA4fGa3jdaXL6tapEmahy%2FcMMjEFDg%2FJ6tdjKC3pfvDPtSOWiTa5KoPMt%2FAHfgSEl2iunVL%2BS75fuisq2pdAvMnFV2E7BQdBqfspikHQ%2FPQNnFGDAT2g4gY2o1OXzxyVI%2BFKGZE92ZjcFUj8hzbKoJUgReDl5C%2F3qPmqMtIN%2BmhyW9R%2F%2FsQKE6uvNQSNHjutrImjZ2RHij42bfEkpZtlE16OfJ6ylPR3nAWqv2a01oK%2FHuCVCPz3%2BclMRGtXVcvhsS%2BttWvGbNMGGlTiccwzj7qoNaqJvq%2Bg943DYb%2FOW2BmEcHLv1JUiRrJsguc2smGghpjVYo%2BZowhvJAf0qJoYHyUe9%2F%2FOGeU1l4xKbdx5MmMKK9%2BGfY3AS2s3IU%2BWPNoYEItc9hKpTLdbKfwlt3RySP3%2FE2uesGyBJfX4UH8JBl3eef9e%2Fx1t9v06MfJedrPRNuOcx4Iv2Npiik5A7PTWo2TfhyEU2rjJPKv%2Bl5JWCwSkXg9LHfTw2Lm9fcBVzBUQ5xmL3qfeQ6jSFo6k3wwx4vHrwY6mgFW%2Bd47nTiSY%2FUPPUdwSILgEkCb8ovGS1FcJR0fAqsgctkhgTMlbZZsXCYuYnu%2BXVy27RLh67FJi%2B5db08FNGUa7Kn2HsBUNHkF9uxtZBiyG7lwLXMpobhzNepa5AwItyGsUBeQCdMDlZe%2FGcOUeQixQfIoHccQrFmhYSEE31xSAVoIJ%2F8OcKdl9PAlx3Wx5ZKwav6NpVfgF9DL&Expires=1710347223",
        "title": "S3 signed url for direct download"
      }
    },
    "created": "2024-03-13T13:48:05Z",
    "description": "GEC",
    "href": "s3://dev-test-processed-sar-data/2023-06-20/d41a5f76-86e0-4e33-972f-9fa36ac5d0eb/2022-10-29-05-34-18_UMBRA-03.tif",
    "roles": [],
    "title": "GEC",
    "type": "image/tiff; application=geotiff; profile=cloud-optimized"
  },
  "2022-10-29-05-34-18_UMBRA-03_METADATA.json": {
    "alternate": {
      "s3_signed": {
        "description": "Expires at: 2024-03-13T16:27:03+00:00",
        "href": "https://dev-test-processed-sar-data.s3.amazonaws.com/2023-06-20/d41a5f76-86e0-4e33-972f-9fa36ac5d0eb/2022-10-29-05-34-18_UMBRA-03_METADATA.json?AWSAccessKeyId=ASIAZUHGNVNLFSHTWTOP&Signature=bovS%2FZ4B8pJpfA4rk57kFyzLv9c%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEFgaCXVzLXdlc3QtMiJHMEUCIQCEU%2B2RbtpxohZXWMi%2Bc46rMk9%2F4WjQQU9zVHlK34MadgIgSRS6%2FbAoARupxYmvs3mi9S61gIxwCzRT38A%2F2Wd%2FWIsq%2FAQIYRACGgw2NjE5MDgyMDQzNzQiDL8hXRWxKVrkuRHxlCrZBEn6osiQg%2Fv4rz%2B1OpbhcoQJW0q%2BVgmXLuKuaNOMejPUe4OjBUThiC7WVQN6Wei3vfwnJGpVEj%2BLC22BO1PYrUqXGUN6uyqpl%2FoRvLx11Q3ymuQknvxg4FjZsbyDmEfttjkeQ7ldWQiw%2FcAkCEEfSU2tNxKEU4UZvBiVl3hkQDnw566%2FiS9p7hEjbR0geuSyLNSaGye11lR1Tlc1lAH9SxzfO6DUv%2FSbOk%2B%2BaLZuTVDMEBErSCN0URFvkePU8DD5wkec1Y%2BD6cjUwdSdJA4fGa3jdaXL6tapEmahy%2FcMMjEFDg%2FJ6tdjKC3pfvDPtSOWiTa5KoPMt%2FAHfgSEl2iunVL%2BS75fuisq2pdAvMnFV2E7BQdBqfspikHQ%2FPQNnFGDAT2g4gY2o1OXzxyVI%2BFKGZE92ZjcFUj8hzbKoJUgReDl5C%2F3qPmqMtIN%2BmhyW9R%2F%2FsQKE6uvNQSNHjutrImjZ2RHij42bfEkpZtlE16OfJ6ylPR3nAWqv2a01oK%2FHuCVCPz3%2BclMRGtXVcvhsS%2BttWvGbNMGGlTiccwzj7qoNaqJvq%2Bg943DYb%2FOW2BmEcHLv1JUiRrJsguc2smGghpjVYo%2BZowhvJAf0qJoYHyUe9%2F%2FOGeU1l4xKbdx5MmMKK9%2BGfY3AS2s3IU%2BWPNoYEItc9hKpTLdbKfwlt3RySP3%2FE2uesGyBJfX4UH8JBl3eef9e%2Fx1t9v06MfJedrPRNuOcx4Iv2Npiik5A7PTWo2TfhyEU2rjJPKv%2Bl5JWCwSkXg9LHfTw2Lm9fcBVzBUQ5xmL3qfeQ6jSFo6k3wwx4vHrwY6mgFW%2Bd47nTiSY%2FUPPUdwSILgEkCb8ovGS1FcJR0fAqsgctkhgTMlbZZsXCYuYnu%2BXVy27RLh67FJi%2B5db08FNGUa7Kn2HsBUNHkF9uxtZBiyG7lwLXMpobhzNepa5AwItyGsUBeQCdMDlZe%2FGcOUeQixQfIoHccQrFmhYSEE31xSAVoIJ%2F8OcKdl9PAlx3Wx5ZKwav6NpVfgF9DL&Expires=1710347223",
        "title": "S3 signed url for direct download"
      }
    },
    "created": "2024-03-13T13:48:06Z",
    "description": "METADATA",
    "href": "s3://dev-test-processed-sar-data/2023-06-20/d41a5f76-86e0-4e33-972f-9fa36ac5d0eb/2022-10-29-05-34-18_UMBRA-03_METADATA.json",
    "roles": ["metadata"],
    "title": "Metadata",
    "type": "application/json"
  }
}

Updated 4 months ago