Searching a STAC API for Items

Authors: Aimee Barciauskas (Development Seed)

Date: December 13, 2022

Description: This tutorial shows the generic item-level STAC search pattern using pystac-client. Use it after you have identified a collection ID and source STAC API, for example from Federated Search.

This notebook uses MAAP STAC as an example, but the same pattern works for other STAC APIs such as NASA CMR STAC or ESA MAAP STAC.

Another way to inspect a STAC API is via a STAC browser when one is available. For MAAP STAC, see the STAC browser.

Drawing

About this workflow

This notebook covers item-level search in a STAC API. The recommended MAAP workflow is:

  1. Use Federated Search to discover relevant collections across catalogs.

  2. Copy the collection ID and source STAC API from the result you want.

  3. Use those values here to search for items.

MAAP STAC is used below as an example endpoint, but you should replace the endpoint and collection ID with the ones that match your collection.

Additional Resources

Importing and Installing Packages

In order to run this notebook you’ll need the following packages:

[1]:

%%capture
%pip install -U pystac-client

[2]:

from pystac_client import Client

Connect to a STAC API

We first connect to the source STAC API by retrieving its landing page with Client.open. Replace URL with the source STAC API returned by Federated Search, and replace COLLECTION_ID with the collection you want to query.

[3]:

# Replace these with the source STAC API and collection ID from Federated Search
URL = "https://stac.maap-project.org/"
COLLECTION_ID = "ESACCI_Biomass_L4_AGB_V4_100m"

cat = Client.open(URL)
cat

[3]:

Inspecting collections

If you want to inspect the collections available from the current endpoint, get_collections() will iterate through them. In many workflows you can skip this because Federated Search already gave you the collection ID you need.

[4]:

stac_collections = list(cat.get_collections())
stac_collections

[4]:

[<CollectionClient id=Landsat8_SurfaceReflectance>,
 <CollectionClient id=Global_PALSAR2_PALSAR_FNF>,
 <CollectionClient id=Global_Forest_Change_2000-2017>,
 <CollectionClient id=AFRISAR_DLR2>,
 <CollectionClient id=AfriSAR_UAVSAR_KZ>,
 <CollectionClient id=AfriSAR_UAVSAR_Ungeocoded_Covariance>,
 <CollectionClient id=AfriSAR_UAVSAR_Normalization_Area>,
 <CollectionClient id=AfriSAR_UAVSAR_Geocoded_SLC>,
 <CollectionClient id=AfriSAR_UAVSAR_Geocoded_Covariance>,
 <CollectionClient id=GlobCover_09>,
 <CollectionClient id=GlobCover_05_06>,
 <CollectionClient id=GEDI_CalVal_Field_Data>,
 <CollectionClient id=AfriSAR_UAVSAR_Coreg_SLC>,
 <CollectionClient id=GEDI_CalVal_Lidar_Data_Compressed>,
 <CollectionClient id=GEDI_CalVal_Lidar_Data>,
 <CollectionClient id=ABoVE_UAVSAR_PALSAR>,
 <CollectionClient id=AFRISAR_DLR>,
 <CollectionClient id=BIOSAR1>,
 <CollectionClient id=icesat2-boreal>,
 <CollectionClient id=ICESat2_Boreal_AGB_tindex_average>,
 <CollectionClient id=NCEO_Africa_AGB_100m_2017>,
 <CollectionClient id=Paraguay_Country_Pilot>,
 <CollectionClient id=ESACCI_Biomass_L4_AGB_V4_100m>,
 <CollectionClient id=NASA_JPL_global_agb_mean_2020>,
 <CollectionClient id=SRTMGL1_COD>]

[5]:

collection = cat.get_collection(COLLECTION_ID)
collection

[5]:

Searching STAC items

Query the /search endpoint of the STAC API to find items in your chosen collection. This method returns an ItemSearch instance which we can then turn into a list.

Read more about additional parameters to the search() method at pystac-client.readthedocs.io.

[6]:

collection_items = list(cat.search(collections=[collection.id], max_items=10).items())
collection_items

[6]:

[<Item id=LC080090662019122401T1-SC20200127151508.tar>,
 <Item id=LC080090652019122401T1-SC20200127151451.tar>,
 <Item id=LC080090642019122401T2-SC20200127163402.tar>,
 <Item id=LC080080662019121701T2-SC20200127163324.tar>,
 <Item id=LC080080652019121701T2-SC20200127163702.tar>,
 <Item id=LC080080642019121701T1-SC20200127162047.tar>,
 <Item id=LC080090662019120801T1-SC20200127162000.tar>,
 <Item id=LC080090652019120801T1-SC20200127151500.tar>,
 <Item id=LC080090642019120801T1-SC20200127163722.tar>,
 <Item id=LC080080662019120101T2-SC20200127161947.tar>]

We can also retrieve a specific item by supplying one of the IDs returned by the collection search. Then we can inspect one of its asset HREFs.

[7]:

item = collection.get_item(collection_items[0].id)
item.assets[list(item.assets.keys())[0]].href

[7]:

's3://nasa-maap-data-store/file-staging/nasa-map/Landsat8_SurfaceReflectance___1/LC080090662019122401T1-SC20200127151508.tar.gz'

Here’s a simplified example using explicit placeholders that you can swap for a different source STAC API, collection ID, and item ID.

[ ]:

# Replace these values with the source STAC API, collection ID, and item ID you want to inspect
URL = "https://stac.maap-project.org/"
COLLECTION_ID = "ESACCI_Biomass_L4_AGB_V4_100m"
ITEM_ID = "S50W080_ESACCI-BIOMASS-L4-AGB-MERGED-100m-2020-fv4.0"
ASSET_KEY = "estimates"

cat = Client.open(URL)
collection = cat.get_collection(COLLECTION_ID)
collection_items = list(cat.search(collections=[COLLECTION_ID], max_items=10).items())
item = collection.get_item(ITEM_ID)
item.assets[ASSET_KEY].href