Searching the STAC Catalog
Authors: Aimee Barciauskas (Development Seed)
Date: December 13, 2022
Description: This tutorial provides a basic introduction to searching the MAAP STAC catalog using pystac-client
.
Another method of searching the STAC catalog is via the STAC browser.
About the STAC Catalog
The MAAP STAC catalog provides discovery of a subset of MAAP datasets. These collections are hosted specifically through the MAAP STAC catalog and are typically not available on NASA’s CMR. 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 S3 metrics, direct collaboration with data team members, and by request.
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
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]:
- type "Catalog"
- id "stac-fastapi"
- stac_version "1.0.0"
- description "STAC API for the MAAP STAC system."
links [] 33 items
0
- rel "self"
- href "https://stac.maap-project.org/"
- type "application/json"
1
- rel "root"
- href "https://stac.maap-project.org/"
- type "application/json"
- title "MAAP STAC API (dev)"
2
- rel "data"
- href "https://stac.maap-project.org/collections"
- type "application/json"
3
- rel "conformance"
- href "https://stac.maap-project.org/conformance"
- type "application/json"
- title "STAC/WFS3 conformance classes implemented by this server"
4
- rel "search"
- href "https://stac.maap-project.org/search"
- type "application/geo+json"
- title "STAC search"
- method "GET"
5
- rel "search"
- href "https://stac.maap-project.org/search"
- type "application/geo+json"
- title "STAC search"
- method "POST"
6
- rel "child"
- href "https://stac.maap-project.org/collections/Landsat8_SurfaceReflectance"
- type "application/json"
- title "Landsat 8 Operational Land Imager (OLI) Surface Reflectance Analysis Ready Data (ARD) V1, Peru and Equatorial Western Africa, April 2013-January 2020"
7
- rel "child"
- href "https://stac.maap-project.org/collections/Global_PALSAR2_PALSAR_FNF"
- type "application/json"
- title "Global 25m Resolution PALSAR-2/PALSAR Forest/Non-Forest Map"
8
- rel "child"
- href "https://stac.maap-project.org/collections/Global_Forest_Change_2000-2017"
- type "application/json"
- title "Global Forest Change 2000-2017"
9
- rel "child"
- href "https://stac.maap-project.org/collections/AFRISAR_DLR2"
- type "application/json"
- title "AFRISAR_DLR2"
10
- rel "child"
- href "https://stac.maap-project.org/collections/AfriSAR_UAVSAR_KZ"
- type "application/json"
- title "AfriSAR UAVSAR Vertical Wavenumber (KZ) Generated Using NISAR Tools"
11
- rel "child"
- href "https://stac.maap-project.org/collections/AfriSAR_UAVSAR_Ungeocoded_Covariance"
- type "application/json"
- title "AfriSAR UAVSAR Ungeocoded Covariance Matrix product Generated Using NISAR Tools"
12
- rel "child"
- href "https://stac.maap-project.org/collections/AfriSAR_UAVSAR_Normalization_Area"
- type "application/json"
- title "AfriSAR UAVSAR Normalization Area Generated Using NISAR Tools"
13
- rel "child"
- href "https://stac.maap-project.org/collections/AfriSAR_UAVSAR_Geocoded_SLC"
- type "application/json"
- title "AfriSAR UAVSAR Geocoded SLCs Generated Using NISAR Tools"
14
- rel "child"
- href "https://stac.maap-project.org/collections/AfriSAR_UAVSAR_Geocoded_Covariance"
- type "application/json"
- title "AfriSAR UAVSAR Geocoded Covariance Matrix product Generated Using NISAR Tools"
15
- rel "child"
- href "https://stac.maap-project.org/collections/GlobCover_09"
- type "application/json"
- title "GlobCover Global Land Cover Product (2009)"
16
- rel "child"
- href "https://stac.maap-project.org/collections/GlobCover_05_06"
- type "application/json"
- title "GlobCover Global Land Cover Product (2005-06)"
17
- rel "child"
- href "https://stac.maap-project.org/collections/GEDI_CalVal_Field_Data"
- type "application/json"
- title "Global Ecosystem Dynamics Investigation (GEDI) Calibration/Validation Field Survey Dataset"
18
- rel "child"
- href "https://stac.maap-project.org/collections/AfriSAR_UAVSAR_Coreg_SLC"
- type "application/json"
- title "AfriSAR UAVSAR Coregistered SLCs Generated Using NISAR Tools"
19
- rel "child"
- href "https://stac.maap-project.org/collections/GEDI_CalVal_Lidar_Data_Compressed"
- type "application/json"
- title "Global Ecosystem Dynamics Investigation (GEDI) Calibration/Validation Airborne Lidar Dataset (Compressed)"
20
- rel "child"
- href "https://stac.maap-project.org/collections/GEDI_CalVal_Lidar_Data"
- type "application/json"
- title "Global Ecosystem Dynamics Investigation (GEDI) Calibration/Validation Airborne Lidar Dataset"
21
- rel "child"
- href "https://stac.maap-project.org/collections/ABoVE_UAVSAR_PALSAR"
- type "application/json"
- title "Arctic-Boreal Vulnerability Experiment Uninhabited Aerial Vehicle Synthetic Aperture Radar Polarimetric SAR"
22
- rel "child"
- href "https://stac.maap-project.org/collections/AFRISAR_DLR"
- type "application/json"
- title "AFRISAR_DLR"
23
- rel "child"
- href "https://stac.maap-project.org/collections/BIOSAR1"
- type "application/json"
- title "BIOSAR1"
24
- rel "child"
- href "https://stac.maap-project.org/collections/icesat2-boreal"
- type "application/json"
- title "Gridded Boreal Aboveground Biomass Density c.2020 at 30m resolution"
25
- rel "child"
- href "https://stac.maap-project.org/collections/ICESat2_Boreal_AGB_tindex_average"
- type "application/json"
- title "ICESat2-Boreal Above Ground Biomass T-Index Average"
26
- rel "child"
- href "https://stac.maap-project.org/collections/NCEO_Africa_AGB_100m_2017"
- type "application/json"
- title "National Centre for Eath Oberservation (NCEO) Africa Aboveground Woody Biomass (AGB) 2017"
27
- rel "child"
- href "https://stac.maap-project.org/collections/Paraguay_Country_Pilot"
- type "application/json"
- title "Paraguay Country Pilot"
28
- rel "child"
- href "https://stac.maap-project.org/collections/ESACCI_Biomass_L4_AGB_V4_100m"
- type "application/json"
- title "ESA CCI Above-Ground Biomass Product Level 4 Version 4"
29
- rel "child"
- href "https://stac.maap-project.org/collections/NASA_JPL_global_agb_mean_2020"
- type "application/json"
- title "NASA JPL Global Above Ground Biomass Mean Prediction 2020"
30
- rel "child"
- href "https://stac.maap-project.org/collections/SRTMGL1_COD"
- type "application/json"
- title "NASA Shuttle Radar Topography Mission Global 1"
31
- rel "service-desc"
- href "https://stac.maap-project.org/api"
- type "application/vnd.oai.openapi+json;version=3.0"
- title "OpenAPI service description"
32
- rel "service-doc"
- href "https://stac.maap-project.org/api.html"
- type "text/html"
- title "OpenAPI service documentation"
stac_extensions [] 1 items
- 0 "https://raw.githubusercontent.com/radiantearth/stac-api-spec/v1.0.0-rc.1/fragments/context/json-schema/schema.json"
conformsTo [] 16 items
- 0 "http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter"
- 1 "http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter"
- 2 "https://api.stacspec.org/v1.0.0-rc.1/item-search#context"
- 3 "https://api.stacspec.org/v1.0.0-rc.1/item-search#filter"
- 4 "https://api.stacspec.org/v1.0.0-rc.1/item-search#fields"
- 5 "https://api.stacspec.org/v1.0.0-rc.1/item-search#filter:basic-cql"
- 6 "https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features"
- 7 "https://api.stacspec.org/v1.0.0-rc.1/item-search#query"
- 8 "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
- 9 "https://api.stacspec.org/v1.0.0-rc.1/item-search#filter:cql-text"
- 10 "https://api.stacspec.org/v1.0.0-rc.1/collections"
- 11 "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30"
- 12 "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core"
- 13 "https://api.stacspec.org/v1.0.0-rc.1/core"
- 14 "https://api.stacspec.org/v1.0.0-rc.1/item-search"
- 15 "https://api.stacspec.org/v1.0.0-rc.1/item-search#sort"
- title "MAAP STAC API (dev)"
Searching Collections
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]:
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(stac_collections[0].id)
collection
[5]:
- type "Collection"
- id "Landsat8_SurfaceReflectance"
- stac_version "1.0.0"
- description "Landsat Analysis Ready Data (ARD) are consistently processed to the highest scientific standards and level of processing required for direct use in monitoring and assessing landscape change. A fundamental goal for Landsat ARD is to significantly reduce the magnitude of data processing for application scientists, who currently have to download and prepare large amounts of Landsat scene-based data for time-series investigative analysis.This Landsat ARD dataset consists of Landsat 8 Operational Land Imager (OLI) Surface Reflectance are generated using the Landsat Surface Reflectance Code (LaSRC) code. Surface reflectance (SR) is generated for the AfriSAR region of interest and consistently processed using per pixel solar zenith angle corrections and gridded to a common cartographic projection.This collection is a subset over Peru (N: -4.73978, S: -9.72818, E: -75.58157, W: -79.80472) and equatorial western Africa (N: 3.93979, S: -5.39294, E: 16.50647, W: 7.9348) for 12 April 2013 to 29 January 2020."
links [] 4 items
0
- rel "items"
- href "https://stac.maap-project.org/collections/Landsat8_SurfaceReflectance/items"
- type "application/geo+json"
1
- rel "parent"
- href "https://stac.maap-project.org/"
- type "application/json"
2
- rel "root"
- href "https://stac.maap-project.org/"
- type "application/json"
- title "MAAP STAC API (dev)"
3
- rel "self"
- href "https://stac.maap-project.org/collections/Landsat8_SurfaceReflectance"
- type "application/json"
item_assets
- title "Landsat 8 Operational Land Imager (OLI) Surface Reflectance Analysis Ready Data (ARD) V1, Peru and Equatorial Western Africa, April 2013-January 2020"
extent
spatial
bbox [] 1 items
0 [] 4 items
- 0 -79.80472
- 1 -9.72818
- 2 16.50647
- 3 3.93979
temporal
interval [] 1 items
0 [] 2 items
- 0 "2013-04-12T09:28:35.404000Z"
- 1 "2020-01-29T00:00:00Z"
- license "not-provided"
Searching STAC Items
Query the /search
endpoint of the STAC catalog to find items in our collection. This method will return 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 get a specific item by supplying one of the IDs from an item in our previous collection search. We are then able to get the HREF of the first asset in our item.
[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:
[ ]:
# Retrieve a specific collection
collection = cat.get_collection("ESACCI_Biomass_L4_AGB_V4_100m")
# Search for items in the collection
collection_items = list(cat.search(collections=["ESACCI_Biomass_L4_AGB_V4_100m"], max_items=10).items())
# Retrieve a specific item
item = collection.get_item("S50W080_ESACCI-BIOMASS-L4-AGB-MERGED-100m-2020-fv4.0")
# List the item's asset href
item.assets["estimates"].href