Searching the STAC Catalog

This tutorial provides a basic introduction to searching the MAAP STAC catalog (https://stac.maap-project.org/) using pystac-client.

Another method of searching the STAC catalog is via the STAC browser.

Drawing

About the STAC Catalog

At this time, the STAC catalog provides discovery of a subset of MAAP datasets. These datasets were selected because MAAP CMR analytics indicated selected datasets were being searched for the most. The data files have not been moved at all in the process of publishing datasets to STAC.

Data will continue to be added to the STAC catalog with priority given to datasets which are known to be in-use by MAAP UWG members through CMR metrics, S3 metrics, direct collaboration with data team members and by request.

Prerequisites

  • pystac-client
  • rioxarray (for opening a raster as an xarray dataset)

Authorship

[1]:

%%capture
!pip install -U pystac-client

[2]:

from pystac_client import Client

STAC Client

We first connect to an API by retrieving the root catalog, or landing page, of the API with the Client.open function.

[3]:

# STAC API root URL
URL = 'https://stac.maap-project.org/'
cat = Client.open(URL)
cat

[3]:

CollectionClient

As with a static catalog the get_collections function will iterate through the Collections in the Catalog. Notice that because this is an API it can get all the Collections through a single call, rather than having to fetch each one individually.

[4]:

for collection in cat.get_all_collections():
    print(collection)

<CollectionClient id=GlobCover_09>
<CollectionClient id=AfriSAR_UAVSAR_Coreg_SLC>
<CollectionClient id=BIOSAR1>
<CollectionClient id=AfriSAR_AGB_Maps_1681>
<CollectionClient id=Landsat8_SurfaceReflectance>
<CollectionClient id=ABLVIS1B>
<CollectionClient id=AfriSAR_UAVSAR_Ungeocoded_Covariance>
<CollectionClient id=GlobCover_05_06>
<CollectionClient id=Global_PALSAR2_PALSAR_FNF>
<CollectionClient id=GEDI02_A>
<CollectionClient id=AFLVIS2>
<CollectionClient id=AFRISAR_DLR>
<CollectionClient id=icesat2-boreal>
<CollectionClient id=AfriSAR_UAVSAR_Normalization_Area>
<CollectionClient id=GEDI_CalVal_Lidar_Data_Compressed>
<CollectionClient id=GEDI_CalVal_Field_Data>
<CollectionClient id=ESACCI_Biomass_L4_AGB_V3_100m_2010>
<CollectionClient id=ESACCI_Biomass_L4_AGB_V3_100m_2018>
<CollectionClient id=ESACCI_Biomass_L4_AGB_V3_100m_2017>
<CollectionClient id=AfriSAR_UAVSAR_Geocoded_SLC>
<CollectionClient id=Global_PALSAR2_PALSAR_Mosiac>
<CollectionClient id=AFRISAR_DLR2>
<CollectionClient id=AfriSAR_UAVSAR_KZ>
<CollectionClient id=GEDI_CalVal_Lidar_Data>
<CollectionClient id=GEDI02_B>
<CollectionClient id=ABoVE_UAVSAR_PALSAR>
<CollectionClient id=Global_Forest_Change_2000-2017>

[5]:

collection = cat.get_collection('ESACCI_Biomass_L4_AGB_V3_100m_2010')
collection

[5]:

STAC Items

The main functions for getting items return iterators, where pystac-client will handle retrieval of additional pages when needed. Note that one request is made for the first ten items, then a second request for the next ten.

[6]:

items = collection.get_items()

# flush stdout so we can see the exact order that things happen
def get_ten_items(items):
    for i, item in enumerate(items):
        print(f"{i}: {item}")
        if i == 9:
            return

print('First page', flush=True)
get_ten_items(items)

First page
0: <Item id=S50W080_ESACCI-BIOMASS-L4-AGB_SD-MERGED-100m-2010-fv3.0>
1: <Item id=S50W080_ESACCI-BIOMASS-L4-AGB-MERGED-100m-2010-fv3.0>
2: <Item id=S50W070_ESACCI-BIOMASS-L4-AGB_SD-MERGED-100m-2010-fv3.0>
3: <Item id=S50W070_ESACCI-BIOMASS-L4-AGB-MERGED-100m-2010-fv3.0>
4: <Item id=S50W060_ESACCI-BIOMASS-L4-AGB_SD-MERGED-100m-2010-fv3.0>
5: <Item id=S50W060_ESACCI-BIOMASS-L4-AGB-MERGED-100m-2010-fv3.0>
6: <Item id=S40W080_ESACCI-BIOMASS-L4-AGB_SD-MERGED-100m-2010-fv3.0>
7: <Item id=S40W080_ESACCI-BIOMASS-L4-AGB-MERGED-100m-2010-fv3.0>
8: <Item id=S40W070_ESACCI-BIOMASS-L4-AGB_SD-MERGED-100m-2010-fv3.0>
9: <Item id=S40W070_ESACCI-BIOMASS-L4-AGB-MERGED-100m-2010-fv3.0>

Discover the URL of one item using xarray

[7]:

item = collection.get_item('S50W080_ESACCI-BIOMASS-L4-AGB_SD-MERGED-100m-2010-fv3.0')
item.assets['data'].href

[7]:

'https://bmap-catalogue-data.oss.eu-west-0.prod-cloud-ocb.orange-business.com/esacci/ESACCI_Biomass_L4_AGB_V3_100m/2010/S50W080_ESACCI-BIOMASS-L4-AGB_SD-MERGED-100m-2010-fv3.0.tif'