{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "e06a27bf",
   "metadata": {},
   "source": [
    "# Item Search with Intersects\n",
    "\n",
    "This notebook shows the use of pystac-client to perform item search with the `intersects` parameter, to restrict the results to an Area of Interest (AOI)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e16077c",
   "metadata": {},
   "source": [
    "# Client\n",
    "\n",
    "We first connect to an API by retrieving the root catalog, or landing page, of the API with the `Client.open` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "98942e75",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from pystac_client import Client\n",
    "from typing import Any, Dict\n",
    "import json\n",
    "\n",
    "# STAC API root URL\n",
    "URL = 'https://planetarycomputer.microsoft.com/api/stac/v1'\n",
    "\n",
    "client = Client.open(URL)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62e26114",
   "metadata": {},
   "source": [
    "# Item Search\n",
    "\n",
    "When the Catalog is a STAC API, we have the ability to search for items based on spatio-temporal properties.\n",
    "\n",
    "The STAC API endpoint `/search` accepts a parameter `intersects` that is a GeoJSON Geometry representing the AOI of the search.\n",
    "\n",
    "The `search` method of the pystac_client `Client` class accepts several different types of objects:\n",
    "\n",
    "1. a string representing a GeoJSON geometry\n",
    "2. a dictionary representing a GeoJSON geometry\n",
    "3. any object that implements a ``__geo_interface__`` property, [an informal specification](https://gist.github.com/sgillies/2217756)    \n",
    "   supported by several libraries for generating a GeoJSON representation from an object. Several prominent libraries support this\n",
    "   protocol for their objects that represent geometries, including [Shapely](https://shapely.readthedocs.io), [ArcPy](https://pro.arcgis.com/en/pro-app/2.8/arcpy/get-started/what-is-arcpy-.htm), [PySAL](https://pysal.org/), [geojson](https://github.com/jazzband/geojson), [pyshp](https://pypi.org/project/pyshp/), [descartes](https://docs.descarteslabs.com/), and [pygeoif](https://github.com/cleder/pygeoif)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d27fabf",
   "metadata": {},
   "source": [
    "## Item Search with AOI as a Dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d8af6334",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# AOI around Delfzijl, in northern Netherlands\n",
    "aoi_as_dict: Dict[str, Any] = {\n",
    "    \"type\": \"Polygon\",\n",
    "    \"coordinates\": [\n",
    "      [\n",
    "        [\n",
    "          6,\n",
    "          53\n",
    "        ],\n",
    "        [\n",
    "          7,\n",
    "          53\n",
    "        ],\n",
    "        [\n",
    "          7,\n",
    "          54\n",
    "        ],\n",
    "        [\n",
    "          6,\n",
    "          54\n",
    "        ],\n",
    "        [\n",
    "          6,\n",
    "          53\n",
    "        ]\n",
    "      ]\n",
    "    ]\n",
    "}\n",
    "\n",
    "search = client.search(\n",
    "    max_items = 25,\n",
    "    collections = \"aster-l1t\",\n",
    "    intersects = aoi_as_dict,\n",
    ")\n",
    "\n",
    "print(f\"AOI as dictionary, found {len(list(search.items()))} items\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9da4956b",
   "metadata": {},
   "source": [
    "## Item Search with AOI as a String"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9a7c9336",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "aoi_as_str: str  = json.dumps(aoi_as_dict)\n",
    "\n",
    "search = client.search(\n",
    "    max_items = 25,\n",
    "    collections = \"aster-l1t\",\n",
    "    intersects = aoi_as_str,\n",
    ")\n",
    "\n",
    "print(f\"AOI as string, found {len(list(search.items()))} items\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f22ffb5a",
   "metadata": {},
   "source": [
    "## Item Search with AOI as a Shapely Geometry Object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a44598ef",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import shapely.geometry\n",
    "\n",
    "aoi_as_shapely_shape = shapely.geometry.shape(aoi_as_dict)\n",
    "\n",
    "search = client.search(\n",
    "    max_items = 25,\n",
    "    collections = \"aster-l1t\",\n",
    "    intersects = aoi_as_shapely_shape,\n",
    ")\n",
    "\n",
    "print(f\"AOI as Shapely Geometry object from shape(), found {len(list(search.items()))} items\")\n",
    "\n",
    "aoi_as_shapely_polygon = shapely.geometry.Polygon(aoi_as_dict[\"coordinates\"][0])\n",
    "\n",
    "search = client.search(\n",
    "    max_items = 25,\n",
    "    collections = \"aster-l1t\",\n",
    "    intersects = aoi_as_shapely_polygon,\n",
    ")\n",
    "\n",
    "print(f\"AOI as Shapely Geometry object with Polygon, found {len(list(search.items()))} items\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f236254",
   "metadata": {},
   "source": [
    "## Item Search with AOI as a \"geojson\" library object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84ce4395",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import geojson\n",
    "\n",
    "aoi_as_geojson_polygon = geojson.Polygon(aoi_as_dict[\"coordinates\"])\n",
    "\n",
    "search = client.search(\n",
    "    max_items = 25,\n",
    "    collections = \"aster-l1t\",\n",
    "    intersects = aoi_as_geojson_polygon,\n",
    ")\n",
    "\n",
    "print(f\"AOI as geojson Polygon, found {len(list(search.items()))} items\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3fe9c255",
   "metadata": {},
   "source": [
    "## Item Search with AOI as a pygeoif Object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a27dcb72",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import pygeoif\n",
    "aoi_as_pygeoif_polygon = pygeoif.geometry.Polygon(aoi_as_dict[\"coordinates\"][0])\n",
    "\n",
    "search = client.search(\n",
    "    max_items = 25,\n",
    "    collections = \"aster-l1t\",\n",
    "    intersects = aoi_as_pygeoif_polygon,\n",
    ")\n",
    "\n",
    "print(f\"AOI as pygeoif Polygon, found {len(list(search.items()))} items\")"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "6b6313dbab648ff537330b996f33bf845c0da10ea77ae70864d6ca8e2699c7ea"
  },
  "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.11.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}