Migrate to STAC API v2
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
andipr
fields are functionally replaced bysar:range_resolution
andsar:azimuth_resolution
, respectively.All four fields were present in the previous version of STAC API whereas in STAC API v2 only
sar:range_resolution
andsar: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