diff --git a/docs/source/technical_tutorials/search/collection_discovery.ipynb b/docs/source/technical_tutorials/search/collection_discovery.ipynb deleted file mode 100644 index 226491b1..00000000 --- a/docs/source/technical_tutorials/search/collection_discovery.ipynb +++ /dev/null @@ -1,784 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "337f5e01-9946-465a-8657-e4153fbac541", - "metadata": {}, - "source": [ - "# BETA - Collection Discovery: searching for collections across multiple APIs using the Federated Collection Discovery API\n", - "\n", - "Author: Henry Rodman (Development Seed)\n", - "\n", - "Date: September 13, 2024\n", - "\n", - "Description: These examples show how to use the Federated Collection Discovery API to search for collections across multiple STAC APIs and/or CMR APIs. There is also an interactive search application for using the API which you can use at [https://discover.maap-project.org](https://discover.maap-project.org).\n", - "\n", - "
\n", - "Note: The Federated Collection Discovery API is not mature and is not yet supported by standard clients like pystac_client yet! Work has begun to upstream the collection filtering capabilities into pystac_client, though.\n", - "
\n", - "\n", - "## Background\n", - "It can be challenging to find the data that you need for an analysis when any of the following are true:\n", - "- you don't know the collection ID for a collection that you know exists\n", - "- you don't know which exact API the data can be accessed from\n", - "- you don't know which collections you even need\n", - "\n", - "Fear not! The Federated Collection Discovery API can help you find the data you need by running your search for collections across several STAC APIs and/or CMR APIs at once.\n", - "\n", - "## Additional resources\n", - "- [Federated Collection Discovery source code](https://github.com/developmentseed/federated-collection-discovery)\n", - "- [Federated Collection Discovery app](https://discover.maap-project.org)\n", - "- [Federated Collection Discovery API docs](https://discover-api.maap-project.org/docs#/default/search_collections_search_get)" - ] - }, - { - "attachments": {}, - "cell_type": "markdown", - "id": "54f09204-99e9-4bb3-b61f-3072b809c23d", - "metadata": {}, - "source": [ - "![Federated Collection Discovery app](./federated_collection_discovery_app.png)" - ] - }, - { - "cell_type": "markdown", - "id": "e48d0f3d-5419-4d54-8447-2f7f10f00498", - "metadata": {}, - "source": [ - "## Federated Collection Discovery API\n", - "The Federated Collection Discovery API provides a STAC API-esque interface for finding collections that match your search criteria\n", - "\n", - "The application will query a list of STAC APIs and/or CMR APIs and, if the [Collection Search STAC API extension](https://github.com/stac-api-extensions/collection-search) is not implemented, it will do a client-side filter that mimics the filters proposed by that extension.\n", - "\n", - "**search parameters**:\n", - "- `bbox`: bounding box coordinates (EPSG:4326)\n", - "- `datetime`: datetime extent\n", - "- `q`: free-text search\n", - "\n", - "**other parametes**:\n", - "- `hint_lang`: programming language for item-level search hint\n", - " - only `python` right now :/ " - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "a26384e7-18fa-423b-ac51-42ae501e9f7b", - "metadata": {}, - "outputs": [], - "source": [ - "from datetime import datetime, timezone\n", - "\n", - "import httpx\n", - "import pandas as pd\n", - "from IPython.display import display, HTML\n", - "\n", - "API_URL = \"https://discover-api.maap-project.org\"" - ] - }, - { - "cell_type": "markdown", - "id": "7d0bed03-d419-44f3-9a51-6d78af677dac", - "metadata": {}, - "source": [ - "The API is configured to search across several STAC APIs by default:" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "91b710d0-7417-4d60-9bb3-092ee5a84297", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'stac_api': ['https://stac.maap-project.org/',\n", - " 'https://openveda.cloud/api/stac/',\n", - " 'https://catalogue.dataspace.copernicus.eu/stac'],\n", - " 'cmr': []}" - ] - }, - "execution_count": 2, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "default_api_urls = httpx.get(f\"{API_URL}/apis\", timeout=20).json()\n", - "default_api_urls" - ] - }, - { - "cell_type": "markdown", - "id": "8408c299-7ea5-4b22-a8ff-759473fa61eb", - "metadata": {}, - "source": [ - "### `free-text` filter\n", - "Perform a search with a free-text filter for collections that include 'elevation' OR 'DEM' but not 'biomass'. The API will scan the 'title', 'description', and 'keywords' attributes of all of the collections in the catalogs.\n", - "\n", - "The free-text query parameter will follow the logic outlined in the [STAC API free-text extension](https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file). Here is a table that outlines the types of queries that are possible (borrowed from the STAC API free-text extension readme):\n", - "| q | Summary | Detail |\n", - "| ----------- | ------- | ------ |\n", - "| `sentinel` | Free-text query against all properties | This will search for any matching items that CONTAIN `\"sentinel\"` |\n", - "| `\"climate model\"` | Free-text search using exact | This will search for any matching items that CONTAIN the exact phrase `\"climate model\"` |\n", - "|`climate model`| Using `OR` term match (**Default**) | This will search for any matching items that CONTAIN `\"climate\"` OR `\"model\"`|\n", - "|`climate OR model`| Using `OR` term match (**Default**) | This will search for any matching items that CONTAIN `\"climate\"` OR `\"model\"`|\n", - "|`climate AND model`| Using `AND` term match | This will search for any matching items that CONTAIN `\"climate\"` AND `\"model\"`|\n", - "| `(quick OR brown) AND fox` | Parentheses can be used to group terms | This will search for matching items that CONTAIN `\"quick\"` OR `\"brown\"` AND `\"fox\"` |\n", - "| `quick +brown -fox` | Indicate included and excluded terms using `+`/`-` | This will search for items that INCLUDES `\"brown\"` EXCLUDES `\"fox\"` OR CONTAIN `\"quick\"` |" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "dac6c45d-d233-4847-b12e-9acb9a803e67", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
idcatalog_urltitle
0ABoVE_UAVSAR_PALSARhttps://stac.maap-project.org/Arctic-Boreal Vulnerability Experiment Uninhabited Aerial Vehicle Synthetic Aperture Radar Polarimetric SAR
1SRTMGL1_CODhttps://stac.maap-project.org/NASA Shuttle Radar Topography Mission Global 1
2COP-DEMhttps://catalogue.dataspace.copernicus.eu/stacCOP-DEM
" - ], - "text/plain": [ - "" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "search_request = httpx.get(\n", - " f\"{API_URL}/search\",\n", - " params={\n", - " \"q\": \"(elevation OR DEM) -biomass\",\n", - " \"hint_lang\": \"python\",\n", - " },\n", - " timeout=20,\n", - ")\n", - "search_request.raise_for_status()\n", - "search_results = search_request.json()\n", - "\n", - "results_df = pd.DataFrame(search_results[\"results\"])\n", - "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" - ] - }, - { - "cell_type": "markdown", - "id": "e4317cdf-5631-46ae-b968-4aea375b2ecd", - "metadata": {}, - "source": [ - "The `results` contain a list of collection-level metadata with some basic properties that you can review further." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "90807432-3d17-43c5-bad9-b1bd1bfd3899", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "id ABoVE_UAVSAR_PALSAR\n", - "catalog_url https://stac.maap-project.org/\n", - "title Arctic-Boreal Vulnerability Experiment Uninhab...\n", - "spatial_extent [[-166.788382, 69.708769, -110.947561, 59.7293...\n", - "temporal_extent [[2017-06-13T22:03:35Z, 2017-06-22T19:25:35Z]]\n", - "short_name None\n", - "description The Arctic-Boreal Vulnerability Experiment (AB...\n", - "keywords []\n", - "hint import pystac_client\\n\\ncatalog = pystac_clien...\n", - "Name: 0, dtype: object\n", - "\n", - "description:\n", - " The Arctic-Boreal Vulnerability Experiment (ABoVE) is a NASA Terrestrial Ecology Program field campaign conducted from June through September 2017 over Alaska and Western Canada. ABoVE is a large-scale study of environmental change and to assess the vulnerability and resilience of Arctic and boreal ecosystems and provide scientific bases for societal response decision making. ABoVE utilized the Uninhabited Aerial Vehicle Synthetic Aperture Radar (UAVSAR) Polarimetric SAR (PALSAR) instrument to provide image transects to survey the land surface, hydrological systems and vegetation. SAR products in this collection include the Digital Elevation Model (DEM), the local incidence angle, the terrain slope product, ground projected complex cross products, the compressed stokes matrix, pauli decompositions, multi-look cross products, and scene annotation files. \n" - ] - } - ], - "source": [ - "collection_info = results_df.iloc[0]\n", - "print(collection_info)\n", - "\n", - "print(\"\\ndescription:\\n\", collection_info.description)" - ] - }, - { - "cell_type": "markdown", - "id": "b5e7f2a9-1dab-4a8d-99ab-32548f2281e7", - "metadata": {}, - "source": [ - "You can also get a code snippet for performing an item-level search against the home API for a particular collection if you provide the `hint_lang` parameter in the request." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "58a78940-f76a-482c-a18a-0a177e1f5778", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "import pystac_client\n", - "\n", - "catalog = pystac_client.Client.open(\"https://stac.maap-project.org/\")\n", - "search = catalog.search(collections=\"ABoVE_UAVSAR_PALSAR\")\n", - "item_collection = search.item_collection()\n", - "\n" - ] - } - ], - "source": [ - "print(collection_info.hint)" - ] - }, - { - "cell_type": "markdown", - "id": "b542b4e3-82b5-4e81-8110-bba176128cc7", - "metadata": {}, - "source": [ - "### `bbox` filter\n", - "Perform a search for collections that intersect Finland's bounding box with a free-text filter for 'biomass'" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "9d528f9a-2a21-4ec5-bccc-89b7ea461b5e", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
idcatalog_urltitle
0GEDI_CalVal_Field_Datahttps://stac.maap-project.org/Global Ecosystem Dynamics Investigation (GEDI) Calibration/Validation Field Survey Dataset
1BIOSAR1https://stac.maap-project.org/BIOSAR1
2ICESat2_Boreal_AGB_tindex_averagehttps://stac.maap-project.org/ICESat2-Boreal Above Ground Biomass T-Index Average
3ESACCI_Biomass_L4_AGB_V4_100mhttps://stac.maap-project.org/ESA CCI Above-Ground Biomass Product Level 4 Version 4
4icesat2-borealhttps://stac.maap-project.org/Gridded Boreal Aboveground Biomass Density c.2020 at 30m resolution
" - ], - "text/plain": [ - "" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "finland_bbox = (18.061, 59.348, 31.181, 70.576)\n", - "search_request = httpx.get(\n", - " f\"{API_URL}/search\",\n", - " params={\n", - " \"q\": \"biomass\",\n", - " \"bbox\": \",\".join(str(coord) for coord in finland_bbox),\n", - " \"hint_lang\": \"python\",\n", - " },\n", - " timeout=20,\n", - ")\n", - "search_request.raise_for_status()\n", - "search_results = search_request.json()\n", - "\n", - "results_df = pd.DataFrame(search_results[\"results\"])\n", - "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "ce19f2b7-bb7b-4c4e-9d68-34d726fc41d6", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "import pystac_client\n", - "\n", - "catalog = pystac_client.Client.open(\"https://stac.maap-project.org/\")\n", - "search = catalog.search(\n", - " collections=\"icesat2-boreal\",\n", - " bbox=(18.061, 59.348, 31.181, 70.576),\n", - ")\n", - "item_collection = search.item_collection()\n", - "\n" - ] - } - ], - "source": [ - "collection_info = results_df.iloc[4]\n", - "\n", - "print(collection_info.hint)" - ] - }, - { - "cell_type": "markdown", - "id": "f98d900f-98c9-4d2f-98e1-cb87987c8ac5", - "metadata": {}, - "source": [ - "## `datetime` filter\n", - "You can use the `datetime` parameter to filter down to collections with temporal extents that overlap a provided range. For example, to find collections with a temporal extent that includes the term 'spectral' and has data as recent as September 15, 2024, you can run the following search:" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "3ed216df-c39f-4541-af86-3381b54f74a2", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
idcatalog_urltemporal_extent
0TERRAAQUAhttps://catalogue.dataspace.copernicus.eu/stac[[2000-02-16T00:00:00Z, None]]
1LANDSAT-8https://catalogue.dataspace.copernicus.eu/stac[[2013-03-24T00:00:00Z, None]]
2SENTINEL-2https://catalogue.dataspace.copernicus.eu/stac[[2015-07-01T00:00:00Z, None]]
" - ], - "text/plain": [ - "" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "recent_date = datetime(year=2024, month=9, day=15, tzinfo=timezone.utc)\n", - "\n", - "search_request = httpx.get(\n", - " f\"{API_URL}/search\",\n", - " params={\n", - " \"datetime\": f\"{recent_date.isoformat()}/..\",\n", - " \"q\": \"spectral\",\n", - " \"hint_lang\": \"python\",\n", - " },\n", - " timeout=20,\n", - ")\n", - "search_request.raise_for_status()\n", - "search_results = search_request.json()\n", - "\n", - "results_df = pd.DataFrame(search_results[\"results\"])\n", - "display(HTML(results_df[[\"id\", \"catalog_url\", \"temporal_extent\"]].to_html()))" - ] - }, - { - "cell_type": "markdown", - "id": "541ca8ca-02c2-417c-aff4-337ea8815ada", - "metadata": {}, - "source": [ - "
\n", - "Note: For open datetime ranges, use .. to represent either the beginning or ending timestamp.\n", - "
" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "a5ad6305-dc0f-4285-8e63-5764e29eeb49", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "import pystac_client\n", - "\n", - "catalog = pystac_client.Client.open(\"https://catalogue.dataspace.copernicus.eu/stac\")\n", - "search = catalog.search(\n", - " collections=\"SENTINEL-2\",\n", - " datetime=\"2024-09-15T00:00:00Z/..\",\n", - ")\n", - "item_collection = search.item_collection()\n", - "\n" - ] - } - ], - "source": [ - "collection_info = results_df.iloc[2]\n", - "\n", - "print(collection_info.hint)" - ] - }, - { - "cell_type": "markdown", - "id": "17f1c3eb-33e3-45e0-9b63-841d99272946", - "metadata": {}, - "source": [ - "## Specify APIs with `stac_api_urls` and/or `cmr_urls`\n", - "You can specify a set of different STAC APIs to search through with the `stac_api_urls` parameter. This will override the default STAC API URLs." - ] - }, - { - "cell_type": "code", - "execution_count": 15, - "id": "88e3178e-1fd4-434d-8f68-e4f16feb5e72", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
idcatalog_urltitle
0MAXAR_Marshall_Fire_21_Updatehttps://stac.eoapi.devMarshall Fire
1MAXAR_McDougallCreekWildfire_BC_Canada_Aug_23https://stac.eoapi.devMcDougall Creek Wildfire
2MAXAR_NWT_Canada_Aug_23https://stac.eoapi.devNorthwest Territories Fires
" - ], - "text/plain": [ - "" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "additional_stac_api_urls = [\n", - " \"https://stac.eoapi.dev\",\n", - " \"https://earth-search.aws.element84.com/v1\"\n", - "]\n", - "search_request = httpx.get(\n", - " f\"{API_URL}/search\",\n", - " params={\n", - " \"stac_api_urls\": \",\".join(additional_stac_api_urls),\n", - " \"q\": \"fire\"\n", - " },\n", - " timeout=30,\n", - ")\n", - "search_request.raise_for_status()\n", - "search_results = search_request.json()\n", - "\n", - "results_df = pd.DataFrame(search_results[\"results\"])\n", - "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" - ] - }, - { - "cell_type": "markdown", - "id": "7af548ef-52f6-4908-9363-cc8ba5f863d3", - "metadata": {}, - "source": [ - "By adding the NASA Operational CMR Search API URL in the `cmr_urls` parameter you can run include the entire CMR catalog in your search and have " - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "id": "5f712582-2d65-4489-8625-7040cc2f32df", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
idcatalog_urltitle
0hls-ndvihttps://openveda.cloud/api/stac/Normalized difference vegetation index from HLS
1hls-l30-002-ej-reprocessedhttps://openveda.cloud/api/stac/HLSL30.002 Environmental Justice Events
2darnah-floodhttps://openveda.cloud/api/stac/False Color Pre and Post Flood
3hls-s30-002-ej-reprocessedhttps://openveda.cloud/api/stac/HLSS30.002 Environmental Justice Events
4hls-ndvi-differencehttps://openveda.cloud/api/stac/HLS-derived NDVI difference for Assessing Impacts from Hurricane Iann
5hls-entropy-differencehttps://openveda.cloud/api/stac/HLS-derived entropy difference for Assessing impacts from Hurricane Ian
6hls-bais2-v2https://openveda.cloud/api/stac/HLS-calculated BAIS2 burned area
7hls-swir-falsecolor-compositehttps://openveda.cloud/api/stac/HLS SWIR FalseColor Composite
8C2021957657-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/HLS Landsat Operational Land Imager Surface Reflectance and TOA Brightness Daily Global 30m v2.0
9C2021957295-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/HLS Sentinel-2 Multi-spectral Instrument Surface Reflectance Daily Global 30m v2.0
10C2746980408-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/OPERA Land Surface Disturbance Alert from Harmonized Landsat Sentinel-2 product (Version 1)
11C2617126679-POCLOUDhttps://cmr.earthdata.nasa.gov/search/OPERA Dynamic Surface Water Extent from Harmonized Landsat Sentinel-2 product (Version 1)
12C2076106409-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/ECOSTRESS Tiled Evapotranspiration Instantaneous and Daytime L3 Global 70 m V002
13C2074877891-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/ECOSTRESS Tiled Downscaled Meteorology Instantaneous L3 Global 70 m V002
14C2074852168-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/ECOSTRESS Tiled Surface Energy Balance Instantaneous L3 Global 70 m V002
15C2519119034-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/OPERA Land Surface Disturbance Annual from Harmonized Landsat Sentinel-2 product (Version 1)
16C2090073749-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/ECOSTRESS Tiled Ancillary NDVI and Albedo L2 Global 70 m V002
17C2595678301-LPCLOUDhttps://cmr.earthdata.nasa.gov/search/ECOSTRESS Tiled Top of Atmosphere Calibrated Radiance Instantaneous L1C Global 70 m V002
18C2756302505-ORNL_CLOUDhttps://cmr.earthdata.nasa.gov/search/Aboveground Biomass Density for High Latitude Forests from ICESat-2, 2020
19C2775078742-ORNL_CLOUDhttps://cmr.earthdata.nasa.gov/search/Phenology derived from Satellite Data and PhenoCam across CONUS and Alaska, 2019-2020
20C2102664483-LPDAAC_ECShttps://cmr.earthdata.nasa.gov/search/MuSLI Multi-Source Land Surface Phenology Yearly North America 30 m V011
" - ], - "text/plain": [ - "" - ] - }, - "metadata": {}, - "output_type": "display_data" - } - ], - "source": [ - "search_request = httpx.get(\n", - " f\"{API_URL}/search\",\n", - " params={\n", - " \"cmr_urls\": \"https://cmr.earthdata.nasa.gov/search/\",\n", - " \"q\": \"HLS\"\n", - " },\n", - " timeout=20,\n", - ")\n", - "search_request.raise_for_status()\n", - "search_results = search_request.json()\n", - "\n", - "results_df = pd.DataFrame(search_results[\"results\"])\n", - "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "ec2f6d3d-0e65-45e0-a394-1a88e3ef60ce", - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python [conda env:pangeo] *", - "language": "python", - "name": "conda-env-pangeo-py" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.10.13" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/docs/source/technical_tutorials/search/federated-collection-discovery/code-hint.png b/docs/source/technical_tutorials/search/federated-collection-discovery/code-hint.png new file mode 100644 index 00000000..1d02c005 Binary files /dev/null and b/docs/source/technical_tutorials/search/federated-collection-discovery/code-hint.png differ diff --git a/docs/source/technical_tutorials/search/federated-collection-discovery/collection-details.png b/docs/source/technical_tutorials/search/federated-collection-discovery/collection-details.png new file mode 100644 index 00000000..b73e0708 Binary files /dev/null and b/docs/source/technical_tutorials/search/federated-collection-discovery/collection-details.png differ diff --git a/docs/source/technical_tutorials/search/federated-collection-discovery/collection_discovery.ipynb b/docs/source/technical_tutorials/search/federated-collection-discovery/collection_discovery.ipynb new file mode 100644 index 00000000..17e5c697 --- /dev/null +++ b/docs/source/technical_tutorials/search/federated-collection-discovery/collection_discovery.ipynb @@ -0,0 +1,1254 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "337f5e01-9946-465a-8657-e4153fbac541", + "metadata": {}, + "source": [ + "# Collection Discovery: searching for collections across multiple APIs using the Federated Collection Discovery tools\n", + "\n", + "Author: Henry Rodman (Development Seed)\n", + "\n", + "Date: December 18, 2025\n", + "\n", + "Description: These examples show how to use the Federated Collection Discovery STAC API to search for collections across multiple STAC APIs. There is also an interactive search application for using the API which you can use at [https://discover.maap-project.org](https://discover.maap-project.org).\n", + "\n", + "## Background\n", + "It can be challenging to find the data that you need for an analysis when any of the following are true:\n", + "- you don't know the collection ID for a collection that you know exists\n", + "- you don't know which exact API the data can be accessed from\n", + "- you don't know which collections you even need\n", + "\n", + "Fear not! The Federated STAC Collection Discovery application (and the underlying API) can help you find the data you need by running your search for collections across multiple catalogs simultaneously.\n", + "\n", + "![Federated Collection Discovery application](./federated-collection-discovery-app.png)\n", + "\n", + "## Using [discover.maap-project.org](https://discover.maap-project.org)\n", + "\n", + "The Federated Collection Discovery web application is a great place to browse for datasets that may be relevant to your work. The application allows you to apply free-text, spatial, and temporal filters to the collections that are housed in a set of configured catalogs. By default, the application will search through the following catalogs:\n", + "\n", + "* NASA MAAP STAC: https://stac.maap-project.org/\n", + "* ESA MAAP STAC: https://catalog.maap.eo.esa.int/catalogue/\n", + "* VEDA STAC: https://openveda.cloud/api/stac/\n", + "* NASA CMR STAC: https://cmr.earthdata.nasa.gov/stac/ALL\n", + "\n", + "You can toggle any of these APIs on/off and add new STAC APIs to the list in the 'Settings' menu:\n", + "\n", + "\n", + "\n", + "
\n", + "Note: Any custom STAC API that you provide must have the free-text and collection-search STAC API extensions enabled. If those extensions are not available then the application will warn you that those search features are not available.\n", + "
\n", + "\n", + "The search form allows you to apply text, temporal, and spatial filters to the collections:\n", + "\n", + "\n", + "\n", + "### text search\n", + "Perform a search with a free-text filter for collections that include 'elevation' OR 'DEM' but not 'biomass'. The API will scan the 'title', 'description', and 'keywords' attributes of all of the collections in the catalogs.\n", + "\n", + "The free-text query parameter will follow the logic outlined in the [STAC API free-text extension](https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file). Here is a table that outlines the types of queries that are possible (borrowed from the STAC API free-text extension readme):\n", + "| q | Summary | Detail |\n", + "| ----------- | ------- | ------ |\n", + "| `sentinel` | Free-text query against all properties | This will search for any matching items that CONTAIN `\"sentinel\"` |\n", + "| `\"climate model\"` | Free-text search using exact | This will search for any matching items that CONTAIN the exact phrase `\"climate model\"` |\n", + "|`climate model`| Using `OR` term match (**Default**) | This will search for any matching items that CONTAIN `\"climate\"` OR `\"model\"`|\n", + "|`climate OR model`| Using `OR` term match (**Default**) | This will search for any matching items that CONTAIN `\"climate\"` OR `\"model\"`|\n", + "|`climate AND model`| Using `AND` term match | This will search for any matching items that CONTAIN `\"climate\"` AND `\"model\"`|\n", + "| `(quick OR brown) AND fox` | Parentheses can be used to group terms | This will search for matching items that CONTAIN `\"quick\"` OR `\"brown\"` AND `\"fox\"` |\n", + "| `quick +brown -fox` | Indicate included and excluded terms using `+`/`-` | This will search for items that INCLUDES `\"brown\"` EXCLUDES `\"fox\"` OR CONTAIN `\"quick\"` |\n", + "\n", + "### spatial search\n", + "You can apply a spatial filter to your search by typing the bounding box coordinates (xmin, ymin, xmax, ymax) or by drawing one on the provided map interface. The bounding box filter will return collections where the spatial extent intersects the provided bounding box.\n", + "\n", + "\n", + "\n", + "### temporal search\n", + "You can apply a temporal filter to your search by entering a start/end date range in the provided input boxes.\n", + "\n", + "### Inspect the search results\n", + "The matching collections from your search query will be printed in a table. If you click on a row, the collection details will pop up showing the description, the spatial and temporal extents, the source catalog, and data provider entries.\n", + "\n", + "\n", + "\n", + "If the collection seems like a good match for your needs, you can scroll down to the 'STAC Item Code Hints' to get the Python and R code you need to do an item-level search in a notebook or script.\n", + "\n", + "\n", + "\n", + "Users can also follow links to the original STAC collection JSON in its home API and browse for items there." + ] + }, + { + "cell_type": "markdown", + "id": "e48d0f3d-5419-4d54-8447-2f7f10f00498", + "metadata": {}, + "source": [ + "## Federated STAC Collection Discovery API\n", + "The web application is powered by the Federated STAC Collection Discovery API which is a STAC API that can be used to run collection searches across multiple upstream STAC APIs simultaneously.\n", + "\n", + "For fully capable upstream STAC APIs, the following parameters are available on the `/collections` endpoint:\n", + "\n", + "**search parameters**:\n", + "- `bbox`: bounding box coordinates (EPSG:4326)\n", + "- `datetime`: datetime extent\n", + "- `q`: free-text search\n", + "- `filter`: cql2 filtering\n", + "- `sortby`: sort results by some field" + ] + }, + { + "cell_type": "markdown", + "id": "ffd97f45-a627-4fe1-8274-ad80cdeee416", + "metadata": {}, + "source": [ + "
\n", + "Note: The API uses the collection-search STAC API extension which can be paired with several other extensions to create a robust search interface for collections across multiple STAC APIs. However, the functionality of the Federated STAC Collection Discovery API is limited to the capabilities of the least capable upstream API. For example, if you try to use it with an upstream STAC API that does not implement the collection-search extension or the free-text search extension, the advanced search capabilities will not be available at all.\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "7072c701-6f73-4c32-81ac-dec54e826976", + "metadata": {}, + "source": [ + "## Searching for collections with pystac-client\n", + "\n", + "Since the Federated Collection Discovery API is a valid STAC API we can use pystac-client to run searches and interact with the results.\n", + "\n", + "This section uses the `CollectionSearch` client from pystac-client which was added in version 0.8.4 so you will need to install `pystac-client>=0.8.4`.\n", + "\n", + "
\n", + "Note: The MAAP ADE has a lower version installed by default so you will need to upgrade the package in your workspace to follow the examples in this notebook!\n", + "
\n", + "\n", + "You can install the required version like this:\n", + "\n", + "```bash\n", + "pip install pystac-client>=0.8.4\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "58be9f7c-fd15-4fc4-b108-6fc91d3f7b25", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "- GEDI_CalVal_Field_Data\n", + " Title: Global Ecosystem Dynamics Investigation (GEDI) Calibration/Validation Field Survey Dataset\n", + " Upstream API link: https://stac.maap-project.org/collections/GEDI_CalVal_Field_Data\n", + " Description: The Global Ecosystem Dynamics Investigation (GEDI) Forest Structure and Biomass Database (FSBD) is a...\n", + "\n", + "- GEDI_ISS_L3_Canopy_Height_Mean_RH100_201904-202303\n", + " Title: GEDI Mean Canopy Height AGL\n", + " Upstream API link: https://staging.openveda.cloud/api/stac/collections/GEDI_ISS_L3_Canopy_Height_Mean_RH100_201904-202303\n", + " Description: The Global Ecosystem Dynamics Investigation ([GEDI](https://gedi.umd.edu/)) mission aims to characte...\n", + "\n", + "- C2141081749-LPCLOUD\n", + " Title: GEDI L1B Geolocated Waveform Data Global Footprint Level V001\n", + " Upstream API link: https://catalog.maap.eo.esa.int/catalogue/collections/C2141081749-LPCLOUD\n", + " Description: GEDI Version 1 data products were decommissioned on February 15, 2022. Users are advised to use the ...\n", + "\n", + "- GEDI02_A_002\n", + " Title: GEDI L2A Elevation and Height Metrics Data Global Footprint Level V002\n", + " Upstream API link: https://cmr.earthdata.nasa.gov/stac/LPCLOUD/collections/GEDI02_A_002\n", + " Description: The Global Ecosystem Dynamics Investigation ([GEDI](https://gedi.umd.edu/)) mission aims to characte...\n" + ] + } + ], + "source": [ + "from pystac_client import Client\n", + "from requests import Request\n", + "\n", + "API_URL = \"https://discover-api.maap-project.org\"\n", + "\n", + "client = Client.open(API_URL)\n", + "\n", + "search = client.collection_search(\n", + " q=\"GEDI\",\n", + " limit=1,\n", + " max_collections=4,\n", + ")\n", + "\n", + "for i, collection in enumerate(search.collections()):\n", + " print(f\"\\n- {collection.id}\")\n", + " print(f\" Title: {collection.title}\")\n", + " print(f\" Upstream API link: {collection.get_self_href()}\")\n", + " description = (\n", + " collection.description[:100] + \"...\"\n", + " if len(collection.description) > 100\n", + " else collection.description\n", + " )\n", + " print(f\" Description: {description}\")" + ] + }, + { + "cell_type": "markdown", + "id": "9eeb4847-8d04-4792-9786-7479ae40af1d", + "metadata": {}, + "source": [ + "### Searching Specific APIs with pystac-client\n", + "\n", + "You can also specify which upstream APIs to query by supplying the `apis` parameter in a `request_modifier` function:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "fdb977fd-d8b7-4e29-a196-0c693af66d68", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Searching specific APIs for biomass collections:\n", + "\n", + "- AFRISAR_DLR\n", + " Title: AFRISAR_DLR\n", + " Upstream API link: https://stac.maap-project.org/collections/AFRISAR_DLR\n", + " Description: The ESA BIOMASS mission was selected in 2013 as the 7th Earth Explorer mission. BIOMAS...\n", + "\n", + "- AFRISAR_DLR2\n", + " Title: AFRISAR_DLR2\n", + " Upstream API link: https://stac.maap-project.org/collections/AFRISAR_DLR2\n", + " Description: The ESA BIOMASS mission was selected in 2013 as the 7th Earth Explorer mission. BIOMASS will provide...\n", + "\n", + "- AfriSAR_UAVSAR_Geocoded_Covariance\n", + " Title: AfriSAR UAVSAR Geocoded Covariance Matrix product Generated Using NISAR Tools\n", + " Upstream API link: https://stac.maap-project.org/collections/AfriSAR_UAVSAR_Geocoded_Covariance\n", + " Description: The Geocoded Covariance Matrix dataset is the 4x4 Native Covariance Matrix geocoded to a spatial res...\n", + "\n", + "- AfriSAR_UAVSAR_Geocoded_SLC\n", + " Title: AfriSAR UAVSAR Geocoded SLCs Generated Using NISAR Tools\n", + " Upstream API link: https://stac.maap-project.org/collections/AfriSAR_UAVSAR_Geocoded_SLC\n", + " Description: The Geocoded SLC (single-look-complex) dataset contains the geolocated SLC magnitude of a particular...\n" + ] + } + ], + "source": [ + "def add_apis(request: Request):\n", + " \"\"\"Add the `apis` parameter to all requests to this STAC API client\"\"\"\n", + " request.params.update(\n", + " {\n", + " \"apis\": [\n", + " \"https://stac.eoapi.dev\",\n", + " \"https://stac.maap-project.org\",\n", + " ]\n", + " }\n", + " )\n", + " return request\n", + "\n", + "\n", + "specific_client = Client.open(API_URL, request_modifier=add_apis)\n", + "\n", + "# Search for biomass collections from specific APIs only\n", + "search = specific_client.collection_search(\n", + " q=\"biomass\",\n", + " limit=1,\n", + " max_collections=4,\n", + ")\n", + "\n", + "print(\"Searching specific APIs for biomass collections:\")\n", + "\n", + "# Show collection details\n", + "for i, collection in enumerate(search.collections()):\n", + " print(f\"\\n- {collection.id}\")\n", + " print(f\" Title: {collection.title}\")\n", + " print(f\" Upstream API link: {collection.get_self_href()}\")\n", + " description = (\n", + " collection.description[:100] + \"...\"\n", + " if len(collection.description) > 100\n", + " else collection.description\n", + " )\n", + " print(f\" Description: {description}\")" + ] + }, + { + "cell_type": "markdown", + "id": "8408c299-7ea5-4b22-a8ff-759473fa61eb", + "metadata": {}, + "source": [ + "## Searching for collections using an http client" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "a26384e7-18fa-423b-ac51-42ae501e9f7b", + "metadata": {}, + "outputs": [], + "source": [ + "from datetime import datetime, timezone\n", + "\n", + "import httpx\n", + "import pandas as pd\n", + "from IPython.display import display, HTML" + ] + }, + { + "cell_type": "markdown", + "id": "7d0bed03-d419-44f3-9a51-6d78af677dac", + "metadata": {}, + "source": [ + "The API is configured to search across several STAC APIs by default, you can use the `/_mgmt/health` endpoint to see the collection-search capabilities to see the collection-search capabilities of each of the configured upstream STAC APIs." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "91b710d0-7417-4d60-9bb3-092ee5a84297", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'status': 'UP',\n", + " 'lifespan': {'status': 'UP'},\n", + " 'upstream_apis': {'https://stac.maap-project.org': {'healthy': True,\n", + " 'collection_search_conformance': ['collection-search',\n", + " 'collection-search#fields',\n", + " 'collection-search#filter',\n", + " 'collection-search#free-text',\n", + " 'collection-search#query',\n", + " 'collection-search#sort']},\n", + " 'https://staging.openveda.cloud/api/stac': {'healthy': True,\n", + " 'collection_search_conformance': ['collection-search',\n", + " 'collection-search#fields',\n", + " 'collection-search#filter',\n", + " 'collection-search#free-text',\n", + " 'collection-search#query',\n", + " 'collection-search#sort']},\n", + " 'https://catalog.maap.eo.esa.int/catalogue': {'healthy': True,\n", + " 'collection_search_conformance': ['collection-search',\n", + " 'collection-search#filter',\n", + " 'collection-search#free-text']},\n", + " 'https://cmr.earthdata.nasa.gov/stac/ALL': {'healthy': True,\n", + " 'collection_search_conformance': ['collection-search',\n", + " 'collection-search#free-text',\n", + " 'collection-search#sort']}}}" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "api_status = httpx.get(f\"{API_URL}/_mgmt/health\", timeout=20).json()\n", + "api_status" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "dac6c45d-d233-4847-b12e-9acb9a803e67", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
idcatalog_urltitle
0ABoVE_UAVSAR_PALSARhttps://stac.maap-project.org/Arctic-Boreal Vulnerability Experiment Uninhabited Aerial Vehicle Synthetic Aperture Radar Polarimetric SAR
1SRTMGL1_CODhttps://stac.maap-project.org/NASA Shuttle Radar Topography Mission Global 1
2la-fires-slopehttps://staging.openveda.cloud/api/stac/Eaton and Palisades Fires (2025) Slope
3la-fires-slope-test-march6https://staging.openveda.cloud/api/stac/Eaton and Palisades Fires (2025) Slope-Test-March6
" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "search_request = httpx.get(\n", + " f\"{API_URL}/collections\",\n", + " params={\n", + " \"q\": \"(elevation OR DEM) -biomass\",\n", + " },\n", + " timeout=20,\n", + ")\n", + "search_request.raise_for_status()\n", + "search_results = search_request.json()\n", + "\n", + "results_df = (\n", + " pd.DataFrame(search_results[\"collections\"])\n", + " .assign(\n", + " catalog_url=lambda df: df[\"links\"].apply(\n", + " lambda links_list: next(\n", + " (link[\"href\"] for link in links_list if link[\"rel\"] == \"root\"), \n", + " None\n", + " )\n", + " )\n", + " )\n", + ")\n", + "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" + ] + }, + { + "cell_type": "markdown", + "id": "e4317cdf-5631-46ae-b968-4aea375b2ecd", + "metadata": {}, + "source": [ + "The `results` contain a list of collection-level metadata with some basic properties that you can review further." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "90807432-3d17-43c5-bad9-b1bd1bfd3899", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "id ABoVE_UAVSAR_PALSAR\n", + "type Collection\n", + "links [{'rel': 'items', 'type': 'application/geo+jso...\n", + "title Arctic-Boreal Vulnerability Experiment Uninhab...\n", + "extent {'spatial': {'bbox': [[-166.788382, 59.729364,...\n", + "license CC0-1.0\n", + "providers [{'url': 'https://above.nasa.gov/', 'name': 'N...\n", + "description The Arctic-Boreal Vulnerability Experiment (AB...\n", + "item_assets {}\n", + "stac_version 1.1.0\n", + "keywords NaN\n", + "stac_extensions NaN\n", + "assets NaN\n", + "renders NaN\n", + "summaries NaN\n", + "datetime_range NaN\n", + "dashboard:is_periodic NaN\n", + "dashboard:time_density NaN\n", + "catalog_url https://stac.maap-project.org/\n", + "Name: 0, dtype: object\n", + "\n", + "description:\n", + " The Arctic-Boreal Vulnerability Experiment (ABoVE) is a NASA Terrestrial Ecology Program field campaign conducted from June through September 2017 over Alaska and Western Canada. ABoVE is a large-scale study of environmental change and to assess the vulnerability and resilience of Arctic and boreal ecosystems and provide scientific bases for societal response decision making. ABoVE utilized the Uninhabited Aerial Vehicle Synthetic Aperture Radar (UAVSAR) Polarimetric SAR (PALSAR) instrument to provide image transects to survey the land surface, hydrological systems and vegetation. SAR products in this collection include the Digital Elevation Model (DEM), the local incidence angle, the terrain slope product, ground projected complex cross products, the compressed stokes matrix, pauli decompositions, multi-look cross products, and scene annotation files. \n" + ] + } + ], + "source": [ + "collection_info = results_df.iloc[0]\n", + "print(collection_info)\n", + "\n", + "print(\"\\ndescription:\\n\", collection_info.description)" + ] + }, + { + "cell_type": "markdown", + "id": "b542b4e3-82b5-4e81-8110-bba176128cc7", + "metadata": {}, + "source": [ + "### bounding box filter\n", + "Perform a search for collections that intersect Finland's bounding box with a free-text filter for 'biomass'" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "9d528f9a-2a21-4ec5-bccc-89b7ea461b5e", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
idcatalog_urltitle
0BIOSAR1https://stac.maap-project.org/BIOSAR1
1ESACCI_Biomass_L4_AGB_V4_100mhttps://stac.maap-project.org/ESA CCI Above-Ground Biomass Product Level 4 Version 4
2GEDI_CalVal_Field_Datahttps://stac.maap-project.org/Global Ecosystem Dynamics Investigation (GEDI) Calibration/Validation Field Survey Dataset
3GEDI_CalVal_Lidar_Data_Compressedhttps://stac.maap-project.org/Global Ecosystem Dynamics Investigation (GEDI) Calibration/Validation Airborne Lidar Dataset (Compressed)
4icesat2-borealhttps://stac.maap-project.org/Circumpolar boreal forest structure from ICESat-2 & HLS (2020 v1.0): 30m aboveground woody biomass density
5ICESat2_Boreal_AGB_tindex_averagehttps://stac.maap-project.org/ICESat2-Boreal Above Ground Biomass T-Index Average
6icesat2-boreal-v2.1-agbhttps://stac.maap-project.org/Circumpolar boreal forest structure from ICESat-2 & HLS (2020 v2.1): 30m aboveground woody biomass density
7icesat2-boreal-v2.1-hthttps://stac.maap-project.org/Circumpolar boreal forest structure from ICESat-2 & HLS (2020 v2.1): 30m vegetation height
8icesat2-boreal-v3.0-agbhttps://stac.maap-project.org/Circumpolar boreal forest structure from ICESat-2 & HLS (2020 v3.0): 30m aboveground woody biomass density
9icesat2-boreal-v3.0-hthttps://stac.maap-project.org/Circumpolar boreal forest structure from ICESat-2 & HLS (2020 v3.0): 30m vegetation height
10BiomassLevel2ahttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 2A
11BiomassLevel1bIOChttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 1B (IOC)
12BiomassLevel1aIOChttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 1A (IOC)
13C3327359101-FEDEOhttps://catalog.maap.eo.esa.int/catalogue/ESA Biomass Climate Change Initiative (Biomass_cci): Global datasets of forest above-ground biomass for the years 2010, 2015, 2016, 2017, 2018, 2019, 2020 and 2021, v5.01
14C3327359400-FEDEOhttps://catalog.maap.eo.esa.int/catalogue/ESA Biomass Climate Change Initiative (Biomass_cci): Global datasets of forest above-ground biomass for the years 2010, 2017, 2018, 2019 and 2020, v4
15BiomassLevel2aIOChttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 2A (IOC)
16BiomassAuxResthttps://catalog.maap.eo.esa.int/catalogue/Biomass Auxiliary Restricted
17BiomassLevel1bhttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 1B
18BiomassCalVal10https://catalog.maap.eo.esa.int/catalogue/Biomass Cal/Val
19BiomassSimulatedhttps://catalog.maap.eo.esa.int/catalogue/Biomass Simulated data
2095913ffb6467447ca72c4e9d8cf30501_NAhttps://cmr.earthdata.nasa.gov/stacESA Biomass Climate Change Initiative (Biomass_cci): Global datasets of forest above-ground biomass for the years 2007, 2010, 2015, 2016, 2017, 2018, 2019, 2020, 2021 and 2022, v6.0
21bf535053562141c6bb7ad831f5998d77_NAhttps://cmr.earthdata.nasa.gov/stacESA Biomass Climate Change Initiative (Biomass_cci): Global datasets of forest above-ground biomass for the years 2010, 2015, 2016, 2017, 2018, 2019, 2020 and 2021, v5.01
225f331c418e9f4935b8eb1b836f8a91b8_NAhttps://cmr.earthdata.nasa.gov/stacESA Biomass Climate Change Initiative (Biomass_cci): Global datasets of forest above-ground biomass for the years 2010, 2017 and 2018, v3
2384403d09cef3485883158f4df2989b0c_NAhttps://cmr.earthdata.nasa.gov/stacESA Biomass Climate Change Initiative (Biomass_cci): Global datasets of forest above-ground biomass for the years 2010, 2017 and 2018, v2
24af60720c1e404a9e9d2c145d2b2ead4e_NAhttps://cmr.earthdata.nasa.gov/stacESA Biomass Climate Change Initiative (Biomass_cci): Global datasets of forest above-ground biomass for the years 2010, 2017, 2018, 2019 and 2020, v4
25Global_Biomass_1950-2010_1296_1https://cmr.earthdata.nasa.gov/stacGlobal 1-degree Maps of Forest Area, Carbon Stocks, and Biomass, 1950-2010
26Boreal_AGB_Density_ICESat2_2186_1https://cmr.earthdata.nasa.gov/stacAboveground Biomass Density for High Latitude Forests from ICESat-2, 2020
27IS2ATBABD_1https://cmr.earthdata.nasa.gov/stacICESat-2 Derived 30 m Along-Track Boreal Aboveground Biomass Density V001
28Boreal_AGB_Density_ICESat2_V3_2437_3https://cmr.earthdata.nasa.gov/stacCircumpolar Boreal Forest Aboveground Biomass Density and Vegetation Height, V3
29CMS_Global_Forest_Age_2345_1https://cmr.earthdata.nasa.gov/stacClassification of Global Forests for IPCC Aboveground Biomass Tier 1 Estimates, 2020
" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "finland_bbox = (18.061, 59.348, 31.181, 70.576)\n", + "search_request = httpx.get(\n", + " f\"{API_URL}/collections\",\n", + " params={\n", + " \"q\": \"biomass\",\n", + " \"bbox\": \",\".join(str(coord) for coord in finland_bbox),\n", + " },\n", + " timeout=20,\n", + ")\n", + "search_request.raise_for_status()\n", + "search_results = search_request.json()\n", + "\n", + "results_df = (\n", + " pd.DataFrame(search_results[\"collections\"])\n", + " .assign(\n", + " catalog_url=lambda df: df[\"links\"].apply(\n", + " lambda links_list: next(\n", + " (link[\"href\"] for link in links_list if link[\"rel\"] == \"root\"), \n", + " None\n", + " )\n", + " )\n", + " )\n", + ")\n", + "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" + ] + }, + { + "cell_type": "markdown", + "id": "fd64651d-5d37-49da-9d05-80d079261a10", + "metadata": {}, + "source": [ + "## pagination\n", + "\n", + "The results returned by the API are paginated, so you can use the `next` link from the `/collections` response to access the next page. Pagination state is handled with the `token` parameter." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "f56945ec-88b6-4df4-9c28-237de56beade", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "https://discover-api.maap-project.org/collections?token=eyJjdXJyZW50Ijp7Imh0dHBzOi8vc3RhYy5tYWFwLXByb2plY3Qub3JnIjoiaHR0cHM6Ly9zdGFjLm1hYXAtcHJvamVjdC5vcmcvY29sbGVjdGlvbnM_YmJveD0xOC4wNjElMkM1OS4zNDglMkMzMS4xODElMkM3MC41NzYmbGltaXQ9MTAmZmlsdGVyX2xhbmc9Y3FsMi10ZXh0JnE9YmlvbWFzcyZvZmZzZXQ9MTAiLCJodHRwczovL2NhdGFsb2cubWFhcC5lby5lc2EuaW50L2NhdGFsb2d1ZSI6Imh0dHBzOi8vY2F0YWxvZy5tYWFwLmVvLmVzYS5pbnQvY2F0YWxvZ3VlL2NvbGxlY3Rpb25zP2Jib3g9MTguMDYxLDU5LjM0OCwzMS4xODEsNzAuNTc2JmxpbWl0PTEwJmZpbHRlcl9sYW5nPWNxbDItdGV4dCZxPWJpb21hc3Mmc3RhcnRSZWNvcmQ9MTEiLCJodHRwczovL2Ntci5lYXJ0aGRhdGEubmFzYS5nb3Yvc3RhYy9BTEwiOiJodHRwczovL2Ntci5lYXJ0aGRhdGEubmFzYS5nb3Yvc3RhYy9BTEwvY29sbGVjdGlvbnM_YmJveD0xOC4wNjElMkM1OS4zNDglMkMzMS4xODElMkM3MC41NzYmZmlsdGVyX2xhbmc9Y3FsMi10ZXh0JmxpbWl0PTEwJnE9YmlvbWFzcyZjdXJzb3I9ZXlKcWMyOXVJam9pV3pFdU5Dd3dMakFzTUM0d0xERTJNRGswTlRreE9UazVPVGtzWENJeklDMGdaM0pwWkdSbFpDQnZZbk5sY25aaGRHbHZibk5jSWl4Y0lrTk5VMTlIYkc5aVlXeGZSbTl5WlhOMFgwRm5aVjh5TXpRMVhDSXNYQ0l4WENJc016QTVNVEUxTXpNM09Td3hORjBpTENKMWJXMGlPaUpiTVM0MExEQXVNQ3d3TGpBc01UWXdPVFExT1RFNU9UazVPU3hjSWpNZ0xTQm5jbWxrWkdWa0lHOWljMlZ5ZG1GMGFXOXVjMXdpTEZ3aVEwMVRYMGRzYjJKaGJGOUdiM0psYzNSZlFXZGxYekl6TkRWY0lpeGNJakZjSWl3ek1Ea3hNVFV6TXpjNUxERTBYU0o5In0sImlzX2ZpcnN0X3BhZ2UiOmZhbHNlfQ==\n" + ] + }, + { + "data": { + "text/html": [ + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
idcatalog_urltitle
0icesat2-boreal-v3.1-agbhttps://stac.maap-project.org/Circumpolar boreal forest structure from ICESat-2 & HLS (2020 v3.1): 30m aboveground woody biomass density
1icesat2-boreal-v3.1-hthttps://stac.maap-project.org/Circumpolar boreal forest structure from ICESat-2 & HLS (2020 v3.1): 30m vegetation height
2BiomassLevel2bIOChttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 2B (IOC)
3BiomassLevel0https://catalog.maap.eo.esa.int/catalogue/Biomass Level 0
4CCIBiomassV5.01https://catalog.maap.eo.esa.int/catalogue/CCI Biomass V5.01
5BiomassLevel2bhttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 2B
6BiomassAuxIOChttps://catalog.maap.eo.esa.int/catalogue/Biomass Auxiliary (IOC)
7BiomassLevel0IOChttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 0 (IOC)
8BiomassLevel1ahttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 1A
9C3904051179-ORNL_CLOUDhttps://catalog.maap.eo.esa.int/catalogue/Circumpolar Boreal Forest Aboveground Biomass Density and Vegetation Height, V3
10C2756302505-ORNL_CLOUDhttps://catalog.maap.eo.esa.int/catalogue/Aboveground Biomass Density for High Latitude Forests from ICESat-2, 2020
11BiomassLevel1cIOChttps://catalog.maap.eo.esa.int/catalogue/Biomass Level 1C (IOC)
12Global_Maps_C_Density_2010_1763_1https://cmr.earthdata.nasa.gov/stacGlobal Aboveground and Belowground Biomass Carbon Density Maps for the Year 2010
13Eurasia_Biomass_1278_1https://cmr.earthdata.nasa.gov/stacLiDAR-based Biomass Estimates, Boreal Forest Biome, Eurasia, 2005-2006
14gov.noaa.nodc:0049894_Not Applicablehttps://cmr.earthdata.nasa.gov/stacSize-fractioned zooplankton biomass data sampled during the Institute of Marine Research Norwegian Sea survey from 1995 to 2005 (NCEI Accession 0049894)
15biomass_allocation_703_1https://cmr.earthdata.nasa.gov/stacBiomass Allocation and Growth Data of Seeded Plants
16gov.noaa.nodc:0049499_Not Applicablehttps://cmr.earthdata.nasa.gov/stacZooplankton biomass measurements collected using bottle from various platforms in the North Pacific Ocean from 1954 to 2001 (NCEI Accession 0049499)
17root_biomass_658_1https://cmr.earthdata.nasa.gov/stacGlobal Distribution of Fine Root Biomass in Terrestrial Ecosystems
18NPP_Grassland_31_654_2https://cmr.earthdata.nasa.gov/stacNPP Grassland: NPP Estimates from Biomass Dynamics for 31 Sites, 1948-1994, R1
19FluxSatMGPP_L3_Daily_p05deg_2.2https://cmr.earthdata.nasa.gov/stacDaily FluxSat GPP of biomass over Land, Based on MODIS Terra and Aqua adjusted reflectance Collection 6.1, on a Global 0.05 by 0.05 Degree Grid, Level 3 Version 2.2
20FluxSatMGPP_L3_Daily_p5deg_2.2https://cmr.earthdata.nasa.gov/stacDaily FluxSat GPP of biomass over Land, Based on MODIS Terra and Aqua adjusted reflectance Collection 6.1, on a Global 0.5 by 0.625 Degree Grid, Level 3 Version 2.2
21TRPSCRECOBM2D_1https://cmr.earthdata.nasa.gov/stacTROPESS Chemical Reanalysis Surface Biomass Burning CO emissions Monthly 2-dimensional Product V1 (TRPSCRECOBM2D) at GES DISC
" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "next_link = next((link[\"href\"] for link in search_results[\"links\"] if link[\"rel\"] == \"next\"), None)\n", + "print(next_link)\n", + "next_results = httpx.get(next_link).json()\n", + "\n", + "results_df = (\n", + " pd.DataFrame(next_results[\"collections\"])\n", + " .assign(\n", + " catalog_url=lambda df: df[\"links\"].apply(\n", + " lambda links_list: next(\n", + " (link[\"href\"] for link in links_list if link[\"rel\"] == \"root\"), \n", + " None\n", + " )\n", + " )\n", + " )\n", + ")\n", + "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" + ] + }, + { + "cell_type": "markdown", + "id": "f98d900f-98c9-4d2f-98e1-cb87987c8ac5", + "metadata": {}, + "source": [ + "## temporal filter\n", + "You can use the `datetime` parameter to filter down to collections with temporal extents that overlap a provided range. For example, to find collections with a temporal extent that includes the term 'spectral' and has data as recent as September 15, 2024, you can run the following search:" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "3ed216df-c39f-4541-af86-3381b54f74a2", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
idcatalog_urltitle
0EOP:ESA:Sentinel-2https://catalog.maap.eo.esa.int/catalogue/Sentinel-2
1ResourceSat-2.archive.and.taskinghttps://catalog.maap.eo.esa.int/catalogue/ResourceSat-2 full archive and tasking
2EarthCAREL0L1Productshttps://catalog.maap.eo.esa.int/catalogue/EarthCARE L0 and L1 Products for the Commissioning Team
3Pleiades.HiRI.archive.and.newhttps://catalog.maap.eo.esa.int/catalogue/Pleiades full archive and tasking
4WorldView-3.full.archive.and.taskinghttps://catalog.maap.eo.esa.int/catalogue/WorldView-3 full archive and tasking
5WorldView-2.full.archive.and.taskinghttps://catalog.maap.eo.esa.int/catalogue/WorldView-2 full archive and tasking
6Vision-1.full.archive.and.taskinghttps://catalog.maap.eo.esa.int/catalogue/Vision-1 full archive and tasking
7EarthCAREL1InstChecked_MAAPhttps://catalog.maap.eo.esa.int/catalogue/EarthCARE L1 Products for Cal/Val Users
8EarthCAREL0L1Products_MAAPhttps://catalog.maap.eo.esa.int/catalogue/EarthCARE L0 and L1 Products for the Commissioning Team
9EarthCAREL1Validated_MAAPhttps://catalog.maap.eo.esa.int/catalogue/EarthCARE L1 Products
10GLHYVI_001https://cmr.earthdata.nasa.gov/stacG-LiHT Hyperspectral Vegetative Indices V001
11GLRADS_001https://cmr.earthdata.nasa.gov/stacG-LiHT Hyperspectral Radiance V001
12GLREFL_001https://cmr.earthdata.nasa.gov/stacG-LiHT Hyperspectral Reflectance V001
13TSIS_SSI_L3_12HR_13https://cmr.earthdata.nasa.gov/stacTSIS SIM Level 3 Solar Spectral Irradiance 12-Hour Means V13 (TSIS_SSI_L3_12HR) at GES DISC
14TSIS_SSI_L3_24HR_13https://cmr.earthdata.nasa.gov/stacTSIS SIM Level 3 Solar Spectral Irradiance 24-Hour Means V13 (TSIS_SSI_L3_24HR) at GES DISC
15f920473c-15a2-490c-8b24-b48f9b8a0226_NAhttps://cmr.earthdata.nasa.gov/stacFirebird MSC - Level 0 Multispectral Images
16HLSS30_2.0https://cmr.earthdata.nasa.gov/stacHLS Sentinel-2 Multi-spectral Instrument Surface Reflectance Daily Global 30m v2.0
17HLSS30_VI_2.0https://cmr.earthdata.nasa.gov/stacHLS Sentinel-2 Multi-spectral Instrument Vegetation Indices Daily Global 30 m V2.0
18SOR3SIMD_027https://cmr.earthdata.nasa.gov/stacSORCE SIM Level 3 Solar Spectral Irradiance Daily Means V027 (SOR3SIMD) at GES DISC
19FORMOSAT-2https://cmr.earthdata.nasa.gov/stacFORMOSAT-2 Panchromatic and Multispectral imagery
" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "recent_date = datetime(year=2024, month=9, day=15, tzinfo=timezone.utc)\n", + "\n", + "search_request = httpx.get(\n", + " f\"{API_URL}/collections\",\n", + " params={\n", + " \"datetime\": f\"{recent_date.isoformat().replace('+00:00', 'Z')}/..\",\n", + " \"q\": \"spectral\",\n", + " },\n", + " timeout=20,\n", + ")\n", + "search_request.raise_for_status()\n", + "search_results = search_request.json()\n", + "\n", + "results_df = (\n", + " pd.DataFrame(search_results[\"collections\"])\n", + " .assign(\n", + " catalog_url=lambda df: df[\"links\"].apply(\n", + " lambda links_list: next(\n", + " (link[\"href\"] for link in links_list if link[\"rel\"] == \"root\"), \n", + " None\n", + " )\n", + " )\n", + " )\n", + ")\n", + "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" + ] + }, + { + "cell_type": "markdown", + "id": "541ca8ca-02c2-417c-aff4-337ea8815ada", + "metadata": {}, + "source": [ + "
\n", + "Note: For open datetime ranges, use .. to represent either the beginning or ending timestamp.\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "17f1c3eb-33e3-45e0-9b63-841d99272946", + "metadata": {}, + "source": [ + "## Specify APIs with `urls`\n", + "You can specify a specific set of STAC APIs to search through with the `apis` parameter. This will override the default STAC API URLs." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "88e3178e-1fd4-434d-8f68-e4f16feb5e72", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
idcatalog_urltitle
0MAXAR_Marshall_Fire_21_Updatehttps://stac.eoapi.dev/Marshall Fire
1MAXAR_Maui_Hawaii_fires_Aug_23https://stac.eoapi.dev/Maui Fires
2MAXAR_McDougallCreekWildfire_BC_Canada_Aug_23https://stac.eoapi.dev/McDougall Creek Wildfire
3MAXAR_NWT_Canada_Aug_23https://stac.eoapi.dev/Northwest Territories Fires
" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "stac_api_urls = [\n", + " \"https://stac.eoapi.dev\",\n", + "]\n", + "search_request = httpx.get(\n", + " f\"{API_URL}/collections\",\n", + " params={\n", + " \"apis\": \",\".join(stac_api_urls),\n", + " \"q\": \"fire\"\n", + " },\n", + " timeout=30,\n", + ")\n", + "search_request.raise_for_status()\n", + "search_results = search_request.json()\n", + "\n", + "results_df = (\n", + " pd.DataFrame(search_results[\"collections\"])\n", + " .assign(\n", + " catalog_url=lambda df: df[\"links\"].apply(\n", + " lambda links_list: next(\n", + " (link[\"href\"] for link in links_list if link[\"rel\"] == \"root\"), \n", + " None\n", + " )\n", + " )\n", + " )\n", + ")\n", + "display(HTML(results_df[[\"id\", \"catalog_url\", \"title\"]].to_html()))" + ] + }, + { + "cell_type": "markdown", + "id": "7af548ef-52f6-4908-9363-cc8ba5f863d3", + "metadata": {}, + "source": [ + "
\n", + "Note: The collection discovery API will only provide search functionality that is provided by ALL of the upstream APIS. If one of the APIs that you want tos earch does not provide the free-text extension, then the `q` parameter will not do anything!\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "36a26ca2-e36f-4f39-88d7-65af72b8eeaf", + "metadata": {}, + "source": [ + "## Additional resources\n", + "- [Federated Collection Discovery source code](https://github.com/developmentseed/federated-collection-discovery)\n", + "- [Federated Collection Discovery app](https://discover.maap-project.org)\n", + "- [Federated Collection Discovery API docs](https://discover-api.maap-project.org/api.html)\n", + "- [STAC FastAPI Collection Discovery User Guide](https://developmentseed.org/stac-fastapi-collection-discovery/v0.2.3/using-the-api/)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.0" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/technical_tutorials/search/federated-collection-discovery/federated-collection-discovery-app.png b/docs/source/technical_tutorials/search/federated-collection-discovery/federated-collection-discovery-app.png new file mode 100644 index 00000000..33e06f03 Binary files /dev/null and b/docs/source/technical_tutorials/search/federated-collection-discovery/federated-collection-discovery-app.png differ diff --git a/docs/source/technical_tutorials/search/federated-collection-discovery/search-form.png b/docs/source/technical_tutorials/search/federated-collection-discovery/search-form.png new file mode 100644 index 00000000..c0e69042 Binary files /dev/null and b/docs/source/technical_tutorials/search/federated-collection-discovery/search-form.png differ diff --git a/docs/source/technical_tutorials/search/federated-collection-discovery/settings.png b/docs/source/technical_tutorials/search/federated-collection-discovery/settings.png new file mode 100644 index 00000000..86a81e57 Binary files /dev/null and b/docs/source/technical_tutorials/search/federated-collection-discovery/settings.png differ diff --git a/docs/source/technical_tutorials/search/federated-collection-discovery/spatial-search.png b/docs/source/technical_tutorials/search/federated-collection-discovery/spatial-search.png new file mode 100644 index 00000000..881c97b0 Binary files /dev/null and b/docs/source/technical_tutorials/search/federated-collection-discovery/spatial-search.png differ diff --git a/docs/source/technical_tutorials/search/federated_collection_discovery_app.png b/docs/source/technical_tutorials/search/federated_collection_discovery_app.png deleted file mode 100644 index 2f388bc0..00000000 Binary files a/docs/source/technical_tutorials/search/federated_collection_discovery_app.png and /dev/null differ diff --git a/docs/source/technical_tutorials/searching.rst b/docs/source/technical_tutorials/searching.rst index efb0707b..dba55ca8 100644 --- a/docs/source/technical_tutorials/searching.rst +++ b/docs/source/technical_tutorials/searching.rst @@ -21,5 +21,5 @@ More information on each catalog and migrating from MAAP's CMR here: `MAAP's Dua search/collections.ipynb search/granules.ipynb search/searching_the_stac_catalog.ipynb - search/collection_discovery.ipynb + search/federated-collection-discovery/collection_discovery.ipynb working_with_r/find_data_in_r.rst