Add bbox and datetime to /collections/{collectionId}/items (#477)

* Add bbox and datetime to ItemCollectionUri

Imported str2list function from stac_fastapi.types.search
as already have dependency on it.

* Add bbox and datetime to ABC item_collection

Using same type signature as get_search

* Add bbox and datetime to PgStac item_collection

Used the same base_args -> clean from the search routes
Probably not necessary in this situation but thought
I'd keep it similar (and extensible).

* Update CHANGES.md

* Add bbox and datetime to SQLAlchemy item_collection

Copy the bbox and datetime filtering from the search routes

* Fix: convert SQLAlchemy bbox to list[int]

* Add item_collection bbox/datetime tests

Author: carderne

CHANGES.md

@@ -5,6 +5,7 @@
 ### Added
 
 * Add support in pgstac backend for /queryables and /collections/{collection_id}/queryables endpoints with functions exposed in pgstac 0.6.8
+* Add `bbox` and `datetime` query parameters to `/collections/{collection_id}/items`. [476](https://github.com/stac-utils/stac-fastapi/issues/476) [380](https://github.com/stac-utils/stac-fastapi/issues/380)
 * Update pgstac requirement to 0.6.10
 
 ### Changed

stac_fastapi/api/stac_fastapi/api/models.py

@@ -13,6 +13,7 @@
     APIRequest,
     BaseSearchGetRequest,
     BaseSearchPostRequest,
+    str2list,
 )
 
 
@@ -123,6 +124,8 @@ class ItemCollectionUri(CollectionUri):
     """Get item collection."""
 
     limit: int = attr.ib(default=10)
+    bbox: Optional[str] = attr.ib(default=None, converter=str2list)
+    datetime: Optional[str] = attr.ib(default=None)
 
 
 class POSTTokenPagination(BaseModel):

stac_fastapi/pgstac/stac_fastapi/pgstac/core.py

@@ -248,6 +248,8 @@ async def _get_base_item(collection_id: str) -> Dict[str, Any]:
     async def item_collection(
         self,
         collection_id: str,
+        bbox: Optional[List[NumType]] = None,
+        datetime: Optional[Union[str, datetime]] = None,
         limit: Optional[int] = None,
         token: str = None,
         **kwargs,
@@ -267,8 +269,21 @@ async def item_collection(
         # If collection does not exist, NotFoundError wil be raised
         await self.get_collection(collection_id, **kwargs)
 
+        base_args = {
+            "collections": [collection_id],
+            "bbox": bbox,
+            "datetime": datetime,
+            "limit": limit,
+            "token": token,
+        }
+
+        clean = {}
+        for k, v in base_args.items():
+            if v is not None and v != []:
+                clean[k] = v
+
         req = self.post_request_model(
-            collections=[collection_id], limit=limit, token=token
+            **clean,
         )
         item_collection = await self._search_base(req, **kwargs)
         links = await CollectionLinks(

stac_fastapi/pgstac/tests/api/test_api.py

@@ -417,6 +417,54 @@ async def test_collection_queryables(load_test_data, app_client, load_test_colle
     assert "eo:cloud_cover" in q["properties"]
 
 
+@pytest.mark.asyncio
+async def test_item_collection_filter_bbox(
+    load_test_data, app_client, load_test_collection
+):
+    coll = load_test_collection
+    first_item = load_test_data("test_item.json")
+    resp = await app_client.post(f"/collections/{coll.id}/items", json=first_item)
+    assert resp.status_code == 200
+
+    bbox = "100,-50,170,-20"
+    resp = await app_client.get(f"/collections/{coll.id}/items", params={"bbox": bbox})
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 1
+
+    bbox = "1,2,3,4"
+    resp = await app_client.get(f"/collections/{coll.id}/items", params={"bbox": bbox})
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 0
+
+
+@pytest.mark.asyncio
+async def test_item_collection_filter_datetime(
+    load_test_data, app_client, load_test_collection
+):
+    coll = load_test_collection
+    first_item = load_test_data("test_item.json")
+    resp = await app_client.post(f"/collections/{coll.id}/items", json=first_item)
+    assert resp.status_code == 200
+
+    datetime_range = "2020-01-01T00:00:00.00Z/.."
+    resp = await app_client.get(
+        f"/collections/{coll.id}/items", params={"datetime": datetime_range}
+    )
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 1
+
+    datetime_range = "2018-01-01T00:00:00.00Z/2019-01-01T00:00:00.00Z"
+    resp = await app_client.get(
+        f"/collections/{coll.id}/items", params={"datetime": datetime_range}
+    )
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 0
+
+
 @pytest.mark.asyncio
 async def test_bad_collection_queryables(
     load_test_data, app_client, load_test_collection

stac_fastapi/sqlalchemy/stac_fastapi/sqlalchemy/core.py

@@ -99,25 +99,64 @@ def get_collection(self, collection_id: str, **kwargs) -> Collection:
             return self.collection_serializer.db_to_stac(collection, base_url)
 
     def item_collection(
-        self, collection_id: str, limit: int = 10, token: str = None, **kwargs
+        self,
+        collection_id: str,
+        bbox: Optional[List[NumType]] = None,
+        datetime: Optional[str] = None,
+        limit: int = 10,
+        token: str = None,
+        **kwargs,
     ) -> ItemCollection:
         """Read an item collection from the database."""
         base_url = str(kwargs["request"].base_url)
         with self.session.reader.context_session() as session:
-            collection_children = (
+            query = (
                 session.query(self.item_table)
                 .join(self.collection_table)
                 .filter(self.collection_table.id == collection_id)
                 .order_by(self.item_table.datetime.desc(), self.item_table.id)
             )
+            # Spatial query
+            geom = None
+            if bbox:
+                bbox = [float(x) for x in bbox]
+                if len(bbox) == 4:
+                    geom = ShapelyPolygon.from_bounds(*bbox)
+                elif len(bbox) == 6:
+                    """Shapely doesn't support 3d bounding boxes so use the 2d portion"""
+                    bbox_2d = [bbox[0], bbox[1], bbox[3], bbox[4]]
+                    geom = ShapelyPolygon.from_bounds(*bbox_2d)
+            if geom:
+                filter_geom = ga.shape.from_shape(geom, srid=4326)
+                query = query.filter(
+                    ga.func.ST_Intersects(self.item_table.geometry, filter_geom)
+                )
+
+            # Temporal query
+            if datetime:
+                # Two tailed query (between)
+                dts = datetime.split("/")
+                # Non-interval date ex. "2000-02-02T00:00:00.00Z"
+                if len(dts) == 1:
+                    query = query.filter(self.item_table.datetime == dts[0])
+                # is there a benefit to between instead of >= and <= ?
+                elif dts[0] not in ["", ".."] and dts[1] not in ["", ".."]:
+                    query = query.filter(self.item_table.datetime.between(*dts))
+                # All items after the start date
+                elif dts[0] not in ["", ".."]:
+                    query = query.filter(self.item_table.datetime >= dts[0])
+                # All items before the end date
+                elif dts[1] not in ["", ".."]:
+                    query = query.filter(self.item_table.datetime <= dts[1])
+
             count = None
             if self.extension_is_enabled("ContextExtension"):
-                count_query = collection_children.statement.with_only_columns(
+                count_query = query.statement.with_only_columns(
                     [func.count()]
                 ).order_by(None)
-                count = collection_children.session.execute(count_query).scalar()
+                count = query.session.execute(count_query).scalar()
             token = self.get_token(token) if token else token
-            page = get_page(collection_children, per_page=limit, page=(token or False))
+            page = get_page(query, per_page=limit, page=(token or False))
             # Create dynamic attributes for each page
             page.next = (
                 self.insert_token(keyset=page.paging.bookmark_next)

stac_fastapi/sqlalchemy/tests/api/test_api.py

@@ -434,3 +434,49 @@ def test_app_search_response_duplicate_forwarded_headers(
     for feature in resp.json()["features"]:
         for link in feature["links"]:
             assert link["href"].startswith("https://testserver:1234/")
+
+
+def test_item_collection_filter_bbox(load_test_data, app_client, postgres_transactions):
+    item = load_test_data("test_item.json")
+    collection = item["collection"]
+    postgres_transactions.create_item(
+        item["collection"], item, request=MockStarletteRequest
+    )
+
+    bbox = "100,-50,170,-20"
+    resp = app_client.get(f"/collections/{collection}/items", params={"bbox": bbox})
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 1
+
+    bbox = "1,2,3,4"
+    resp = app_client.get(f"/collections/{collection}/items", params={"bbox": bbox})
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 0
+
+
+def test_item_collection_filter_datetime(
+    load_test_data, app_client, postgres_transactions
+):
+    item = load_test_data("test_item.json")
+    collection = item["collection"]
+    postgres_transactions.create_item(
+        item["collection"], item, request=MockStarletteRequest
+    )
+
+    datetime_range = "2020-01-01T00:00:00.00Z/.."
+    resp = app_client.get(
+        f"/collections/{collection}/items", params={"datetime": datetime_range}
+    )
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 1
+
+    datetime_range = "2018-01-01T00:00:00.00Z/2019-01-01T00:00:00.00Z"
+    resp = app_client.get(
+        f"/collections/{collection}/items", params={"datetime": datetime_range}
+    )
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 0

stac_fastapi/types/stac_fastapi/types/core.py

@@ -489,7 +489,13 @@ def get_collection(self, collection_id: str, **kwargs) -> stac_types.Collection:
 
     @abc.abstractmethod
     def item_collection(
-        self, collection_id: str, limit: int = 10, token: str = None, **kwargs
+        self,
+        collection_id: str,
+        bbox: Optional[List[NumType]] = None,
+        datetime: Optional[Union[str, datetime]] = None,
+        limit: int = 10,
+        token: str = None,
+        **kwargs,
     ) -> stac_types.ItemCollection:
         """Get all items from a specific collection.
 
@@ -684,7 +690,13 @@ async def get_collection(
 
     @abc.abstractmethod
     async def item_collection(
-        self, collection_id: str, limit: int = 10, token: str = None, **kwargs
+        self,
+        collection_id: str,
+        bbox: Optional[List[NumType]] = None,
+        datetime: Optional[Union[str, datetime]] = None,
+        limit: int = 10,
+        token: str = None,
+        **kwargs,
     ) -> stac_types.ItemCollection:
         """Get all items from a specific collection.