Skip to main content

STAC API

How to access terrabyte data via STAC API​

A short word on STAC​

STAC is the central way of accessing any spatio-temporal data on terrabyte. See here for an introduction and the detailed sepcification:

Principally, data is offered over a catalog containing data from various sources. This catalog is further sub-divided into collections. A collection could for example contain a certain satellite data product like Sentinel-1 GRD, SLC or Sentinel-2 L2A. Each collection consists of multiple items, which might represent individual satellite scenes or product tiles (e.g. the MGRS tiles of Sentinel-2). Each item consists of one or many assets, which contain links to the actual data. For example individual GeoTIFF files for each band.

The terrabyte STAC catalog URL is https://stac.terrabyte.lrz.de/public/api.

For Python there exists the library pystac-client to easily connect and search in the STAC API. If you do not use Python or do not have the possibility to use pystac-client, you can write your own requests to the STAC API. Please have a look at the API definition and which kind of HTTP request you can conduct: https://stac.terrabyte.lrz.de/public/api/api.html

Further down you will find examples on how to list all available collections and how to query the STAC catalog in Python using the pystac library. The content can also be explored by opening the above link in a browser.

STAC pystac exploration

From there you can navigate to individual collections and explore their metadata content for search queries. For example, under https://stac.terrabyte.lrz.de/public/api/collections/sentinel-2-c1-l2a/items → features → 0 → properties we can list the properties of the first item of the sentinel-2-c1-l2a collection. This list contains, amongst others, the entries eo:cloud_cover and s2:mgrs_tile, which will be queried in the tutorial below. The namespaces eo, grid, proj, mgrs, sat and view refer to dedicated STAC extensions. s2 is a custom namespace for expressing Sentinel-2 specific metadata that cannot be described in other STAC extensions.

STAC pystac explore collection

Explore the STAC catalog​

from pystac_client import Client as pystacclient
catalog = pystacclient.open('https://stac.terrabyte.lrz.de/public/api')

# list the IDs of all STAC catalog collections
for collection in catalog.get_all_collections():
    print(collection.id)

Query data from the STAC catalog​

gte and lte describe greater than or equal and lower than or equal, respectively.

start = '2022-01-01T00:00:00Z'
end = '2022-12-31T23:59:59Z'
collection = 'sentinel-2-c1-l2a'
mgrs = 'MGRS-33UPU' 

query = {
    'eo:cloud_cover': {
        "gte": 0,
        "lte": 30
    },
    'grid:code': {'eq': mgrs}
}

results = catalog.search(
    collections=[collection],
    datetime=[start, end],
    query=query,
)
items = results.item_collection_as_dict()
print("%s items found" % len(items['features']))

List items as Pandas GeoDataFrame​

import geopandas as gpd
dataframe = gpd.GeoDataFrame.from_features(items)
dataframe

dataframe visualization

Visualize the covered area​

import folium
import folium.plugins as folium_plugins

map = folium.Map(tiles='Stamen Terrain')
layer_control = folium.LayerControl(position='topright', collapsed=True)
fullscreen = folium_plugins.Fullscreen()
style = {'fillColor': '#00000000', "color": "#0000ff", "weight": 1}

footprints = folium.GeoJson(
    dataframe.to_json(),
    name='Stac Item footprints',
    style_function=lambda x: style,
    control=True
)

footprints.add_to(map)
layer_control.add_to(map)
fullscreen.add_to(map)
map.fit_bounds(map.get_bounds())
map

map visualization