STAC items

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: `Point` `MultiPoint` `LineString` `MultiLineString` `Polygon` `MultiPolygon`
`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"
}