Overview
A STAC item is an individual scene that represents inseparable data and metadata. A STAC item has a unique spatiotemporal extent, that is, has one AOI and acquisition time in its characteristics. For example, an order with a stereo acquisition mode will produce a STAC collection with two STAC items — one for each image of a slightly different AOI.
In UP42 API every STAC item is attributed to a STAC collection.
For more information on STAC items, see Intro to STAC and STAC Item Specification.
See STAC items in a STAC collection
To get a list of all STAC items from a particular STAC collection in your storage, call the /v2/assets/stac/collections/{collection-id}/items endpoint with a specific STAC collection ID as a path parameter.
To search for STAC items with specific parameters instead, make a detailed search.
Request
GET /v2/assets/stac/collections/{collection-id}/items HTTP/1.1
Host: api.up42.com
Authorization: Bearer {token}
Query parameter | Overview |
---|---|
limit | integer The number of STAC items on a results page. |
token | string Search for previous ( prev:{ID} ) or next (next:{ID} ) STAC items from the results page. |
Response
See response example
{
"links": [
{
"href": "https://api.up42.com/v2/assets/stac/",
"rel": "root",
"type": "application/json"
},
{
"href": "https://api.up42.com/v2/assets/stac/collections/596f160c-612d-4e71-a044-56a117fa49f5",
"rel": "parent",
"type": "application/json"
},
{
"href": "https://api.up42.com/v2/assets/stac/collections/596f160c-612d-4e71-a044-56a117fa49f5/items",
"rel": "self",
"type": "application/json"
}
],
"type": "FeatureCollection",
"features": [
{
"assets": {
"8rqzp45j_HH.tif": {
"href": "https://api.up42.com/v2/assets/e4a15000-890b-445c-82bb-e4364baac40b",
"title": "Data",
"type": "image/tiff; application=geotiff; profile=cloud-optimized",
"roles": ["data"]
},
"8rqzp45j_stac_metadata.json": {
"href": "https://api.up42.com/v2/assets/e165b992-f32c-4aac-ab7c-e1d289565efa",
"title": "STAC metadata",
"type": "application/json",
"roles": ["metadata", "stac"]
},
"8rqzp45j_thumbnail.png": {
"href": "https://api.up42.com/v2/assets/e5b17010-730a-445c-82bb-e4364baac32c",
"title": "Thumbnail",
"type": "image/png",
"roles": ["thumbnail"]
},
"8rqzp45j_preview.tif": {
"href": "https://api.up42.com/v2/assets/a265b982-a33b-5aab-ab8b-a2d289566bab",
"title": "Visual",
"type": "image/tiff; application=geotiff; cloud-optimized=true",
"roles": ["visual", "data"]
}
},
"links": [
{
"href": "https://api.up42.com/v2/assets/stac/collections/596f160c-612d-4e71-a044-56a117fa49f5/items/a12f87a3-2776-4315-af89-57c305bd4f6d",
"rel": "self",
"type": "application/geo+json"
},
{
"href": "https://api.up42.com/v2/assets/stac/collections/596f160c-612d-4e71-a044-56a117fa49f5",
"rel": "parent",
"type": "application/json"
},
{
"href": "https://api.up42.com/v2/assets/stac/collections/596f160c-612d-4e71-a044-56a117fa49f5",
"rel": "collection",
"type": "application/json"
},
{
"href": "https://api.up42.com/v2/assets/stac/",
"rel": "root",
"type": "application/json"
}
],
"stac_extensions": [
"https://api.up42.com/stac-extensions/up42-system/v1.0.0/schema.json",
"https://stac-extensions.github.io/projection/v1.0.0/schema.json",
"https://stac-extensions.github.io/eo/v1.0.0/schema.json",
"https://stac-extensions.github.io/view/v1.0.0/schema.json",
"https://api.up42.com/stac-extensions/up42-user/v1.0.0/schema.json"
],
"geometry": {
"type": "Polygon",
"coordinates": [
[
[52.4941111111112, 13.4025555555556],
[52.4941111111112, 13.4111666666667],
[52.4911111111112, 13.4111666666667],
[52.4911111111112, 13.4025555555556],
[52.4941111111112, 13.4025555555556],
[52.4941111111112, 13.4025555555556]
]
]
},
"bbox": [52.4911111111112, 13.4025555555556, 52.4941111111112, 13.4111666666667],
"properties": {
"gsd": 9.118863577837482,
"datetime": "2021-01-15T10:30:15.642354+00:00",
"platform": "TripleSat Constellation-1",
"proj:epsg": 4326,
"providers": [
{
"url": "https://www.21at.sg/",
"name": "Twenty First Century Aerospace Technology (Asia) Pte. Ltd. (21AT Asia)",
"roles": ["producer"]
},
{
"url": "https://www.up42.com",
"name": "UP42",
"roles": ["host"]
}
],
"instruments": ["MS", "PAN"],
"start_datetime": "2021-01-15T10:30:15.363880+00:00",
"end_datetime": "2021-01-15T10:30:15.920828+00:00",
"view:azimuth": 352.997722256726,
"constellation": "SPOT",
"eo:cloud_cover": 0.0,
"view:sun_azimuth": 148.73406037959936,
"view:sun_elevation": 56.49928239650915,
"up42-system:asset_id": "bf9b32f5-ace5-45e4-843b-4d5a62124503",
"view:incidence_angle": 11.704523276124347,
"up42-system:account_id": "8cd5de7b-82e2-4625-b094-d5392f1cf780",
"up42-system:workspace_id": "7d1cf222-1fa7-468c-a93a-3e3188875997"
},
"type": "Feature",
"stac_version": "1.0.0",
"id": "a12f87a3-2776-4315-af89-57c305bd4f6d",
"collection": "596f160c-612d-4e71-a044-56a117fa49f5"
}
]
}
Parameter | Overview |
---|---|
links | array of objects A list of links related to the current endpoint. Use to navigate through objects. |
type | string The type of STAC object. |
features | array of objects A list of STAC items in the STAC collection. |
Parameters of the features array | |
assets | object A list of STAC assets. Learn more about STAC asset parameters. |
links | array of objects A list of links related to the current endpoint. Use to navigate through objects. |
stac_extensions | array of strings A list of STAC extension URLs activated for the current endpoint. For more information, see STAC extensions. |
geometry | object The STAC item AOI. |
geometry.type | string The geometry type. The allowed types:
|
geometry.coordinates | array of arrays The coordinates of the AOI. |
bbox | array of arrays The bounding box that encloses the STAC item geometry. |
properties | object A list of additional STAC item metadata. For more information, see STAC Item Specification. STAC item parameters with {prefixes}: are described in corresponding JSON schemas in features.stac_extensions . |
properties. gsd | float The ground sample distance, in meters. |
properties. datetime | string The date and time when the sensor acquired the data. |
properties. start_datetime | string The date and time when the sensor started the acquisition process. |
properties. end_datetime | string The date and time when the sensor finished the acquisition process. |
properties. constellation | string The name of the sensor. |
stac_version | string The UP42 STAC API version. |
id | string The ID of the STAC item. |
type | string The type of STAC object. |
collection | string The ID of the STAC collection the STAC item belongs to. |
Parameters of the links and features.links arrays | |
href | string The URL of the related endpoint. |
type | string The media type the link returns. |
rel | string The type of relation of the link in links.href to the current endpoint. |
body | object The request body to be used with links.href to call the endpoint. |
method | string The HTTP method to be used with links.href to call the endpoint. |
title | string The link title. |
See a particular STAC item
To get information about one STAC item and all its related STAC assets, call the /v2/assets/stac/collections/{collection-id}/items/{item-id} endpoint with specific STAC collection ID and item ID as path parameters.
Request
GET /v2/assets/stac/collections/{collection-id}/items/{item-id} HTTP/1.1
Host: api.up42.com
Authorization: Bearer {token}
Response
The response is an object from a features
array.
See response example
{
"assets": {
"8rqzp45j_HH.tif": {
"href": "https://api.up42.com/v2/assets/e4a15000-890b-445c-82bb-e4364baac40b",
"title": "Data",
"type": "image/tiff; application=geotiff; profile=cloud-optimized",
"roles": ["data"]
},
"8rqzp45j_stac_metadata.json": {
"href": "https://api.up42.com/v2/assets/e165b992-f32c-4aac-ab7c-e1d289565efa",
"title": "STAC metadata",
"type": "application/json",
"roles": ["metadata", "stac"]
},
"8rqzp45j_thumbnail.png": {
"href": "https://api.up42.com/v2/assets/e5b17010-730a-445c-82bb-e4364baac32c",
"title": "Thumbnail",
"type": "image/png",
"roles": ["thumbnail"]
},
"8rqzp45j_preview.tif": {
"href": "https://api.up42.com/v2/assets/a265b982-a33b-5aab-ab8b-a2d289566bab",
"title": "Visual",
"type": "image/tiff; application=geotiff; cloud-optimized=true",
"roles": ["visual", "data"]
}
},
"links": [
{
"href": "https://api.up42.com/v2/assets/stac/collections/596f160c-612d-4e71-a044-56a117fa49f5/items/a12f87a3-2776-4315-af89-57c305bd4f6d",
"rel": "self",
"type": "application/geo+json"
},
{
"href": "https://api.up42.com/v2/assets/stac/collections/596f160c-612d-4e71-a044-56a117fa49f5",
"rel": "parent",
"type": "application/json"
},
{
"href": "https://api.up42.com/v2/assets/stac/collections/596f160c-612d-4e71-a044-56a117fa49f5",
"rel": "collection",
"type": "application/json"
},
{
"href": "https://api.up42.com/v2/assets/stac/",
"rel": "root",
"type": "application/json"
}
],
"stac_extensions": [
"https://stac-extensions.github.io/projection/v1.0.0/schema.json",
"https://stac-extensions.github.io/eo/v1.0.0/schema.json",
"https://stac-extensions.github.io/view/v1.0.0/schema.json",
"https://api.up42.com/stac-extensions/up42-system/v1.0.0/schema.json"
],
"geometry": {
"type": "Polygon",
"coordinates": [
[
[52.4941111111112, 13.4025555555556],
[52.4941111111112, 13.4111666666667],
[52.4911111111112, 13.4111666666667],
[52.4911111111112, 13.4025555555556],
[52.4941111111112, 13.4025555555556],
[52.4941111111112, 13.4025555555556]
]
]
},
"bbox": [52.4911111111112, 13.4025555555556, 52.4941111111112, 13.4111666666667],
"properties": {
"gsd": 9.118863577837482,
"datetime": "2021-05-31T09:51:52.100000+00:00",
"platform": "SPOT-7",
"proj:epsg": 4326,
"end_datetime": "2021-05-31T09:51:52.100000+00:00",
"view:azimuth": 352.997722256726,
"constellation": "SPOT",
"eo:cloud_cover": 0.0,
"view:sun_azimuth": 148.73406037959936,
"view:sun_elevation": 56.49928239650915,
"up42-system:asset_id": "bf9b32f5-ace5-45e4-843b-4d5a62124503",
"view:incidence_angle": 11.704523276124347,
"up42-system:account_id": "8cd5de7b-82e2-4625-b094-d5392f1cf780",
"up42-system:workspace_id": "7d1cf222-1fa7-468c-a93a-3e3188875997"
},
"type": "Feature",
"stac_version": "1.0.0",
"id": "a12f87a3-2776-4315-af89-57c305bd4f6d",
"collection": "596f160c-612d-4e71-a044-56a117fa49f5"
}