fix: the default and max allowed returned values for collections and items

Ensure collections and items endpoints use their respective default and maximum limit values.

Author: Yuri Zmytrakov

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Changed
 
+- Changed the default and maximum pagination limits for collections/items endpoints. [#482](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/482)
+
 ### Fixed
 
 [v6.5.0] - 2025-09-29

README.md

@@ -299,7 +299,10 @@ You can customize additional settings in your `.env` file:
 | `ENABLE_COLLECTIONS_SEARCH`  | Enable collection search extensions (sort, fields, free text search, structured filtering, and datetime filtering) on the core `/collections` endpoint. | `true`                   | Optional                                                                                    |
 | `ENABLE_COLLECTIONS_SEARCH_ROUTE` | Enable the custom `/collections-search` endpoint (both GET and POST methods). When disabled, the custom endpoint will not be available, but collection search extensions will still be available on the core `/collections` endpoint if `ENABLE_COLLECTIONS_SEARCH` is true. | `false` | Optional |
 | `ENABLE_TRANSACTIONS_EXTENSIONS` | Enables or disables the Transactions and Bulk Transactions API extensions. This is useful for deployments where mutating the catalog via the API should be prevented. If set to `true`, the POST `/collections` route for search will be unavailable in the API. | `true` | Optional |
-| `STAC_ITEM_LIMIT` | Sets the environment variable for result limiting to SFEOS for the number of returned items and STAC collections. | `10` | Optional |
+| `STAC_GLOBAL_COLLECTION_MAX_LIMIT` | Configures the maximum number of STAC collections that can be returned in a single search request. | `300` | Optional |
+| `STAC_DEFAULT_COLLECTION_LIMIT` | Configures the default number of STAC collections returned when no limit parameter is specified in the request. | `100` | Optional |
+| `STAC_GLOBAL_ITEM_MAX_LIMIT` | Configures the maximum number of STAC items that can be returned in a single search request. | `100` | Optional |
+| `STAC_DEFAULT_ITEM_LIMIT` | Configures the default number of STAC items returned when no limit parameter is specified in the request. | `10` | Optional |
 | `STAC_INDEX_ASSETS` | Controls if Assets are indexed when added to Elasticsearch/Opensearch. This allows asset fields to be included in search queries. | `false` | Optional |
 | `ENV_MAX_LIMIT` | Configures the environment variable in SFEOS to override the default `MAX_LIMIT`, which controls the limit parameter for returned items and STAC collections. | `10,000` | Optional |
 | `USE_DATETIME` | Configures the datetime search behavior in SFEOS. When enabled, searches both datetime field and falls back to start_datetime/end_datetime range for items with null datetime. When disabled, searches only by start_datetime/end_datetime range. | `true` | Optional |

stac_fastapi/core/stac_fastapi/core/core.py

@@ -270,33 +270,27 @@ async def all_collections(
         base_url = str(request.base_url)
 
         # Get the global limit from environment variable
-        global_limit = None
-        env_limit = os.getenv("STAC_ITEM_LIMIT")
-        if env_limit:
-            try:
-                global_limit = int(env_limit)
-            except ValueError:
-                # Handle invalid integer in environment variable
-                pass
-
-        # Apply global limit if it exists
-        if global_limit is not None:
-            # If a limit was provided, use the smaller of the two
-            if limit is not None:
-                limit = min(limit, global_limit)
-            else:
-                limit = global_limit
+        global_max_limit = int(os.getenv("STAC_GLOBAL_COLLECTION_MAX_LIMIT", 300))
+        default_limit = int(os.getenv("STAC_DEFAULT_COLLECTION_LIMIT", 100))
+        query_limit = request.query_params.get("limit")
+
+        body_limit = None
+        try:
+            if request.method == "POST" and request.body():
+                body_data = await request.json()
+                body_limit = body_data.get("limit")
+        except Exception:
+            pass
+
+        if body_limit is not None:
+            limit = int(body_limit)
+        elif query_limit:
+            limit = int(query_limit)
         else:
-            # No global limit, use provided limit or default
-            if limit is None:
-                query_limit = request.query_params.get("limit")
-                if query_limit:
-                    try:
-                        limit = int(query_limit)
-                    except ValueError:
-                        limit = 10
-                else:
-                    limit = 10
+            limit = default_limit
+
+        if global_max_limit > 0:
+            limit = min(limit, global_max_limit)
 
         token = request.query_params.get("token")
 
@@ -562,7 +556,7 @@ async def item_collection(
             request (Request): FastAPI Request object.
             bbox (Optional[BBox]): Optional bounding box filter.
             datetime (Optional[str]): Optional datetime or interval filter.
-            limit (Optional[int]): Optional page size. Defaults to env ``STAC_ITEM_LIMIT`` when unset.
+            limit (Optional[int]): Optional page size. Defaults to env `STAC_DEFAULT_ITEM_LIMIT` when unset.
             sortby (Optional[str]): Optional sort specification. Accepts repeated values
                 like ``sortby=-properties.datetime`` or ``sortby=+id``. Bare fields (e.g. ``sortby=id``)
                 imply ascending order.
@@ -660,7 +654,17 @@ async def get_search(
         Raises:
             HTTPException: If any error occurs while searching the catalog.
         """
-        limit = int(request.query_params.get("limit", os.getenv("STAC_ITEM_LIMIT", 10)))
+        global_max_limit = int(os.getenv("STAC_GLOBAL_ITEM_MAX_LIMIT", 100))
+        default_limit = int(os.getenv("STAC_DEFAULT_ITEM_LIMIT", 10))
+
+        query_limit = request.query_params.get("limit")
+        if query_limit:
+            limit = int(query_limit)
+        else:
+            limit = default_limit
+
+        if global_max_limit > 0:
+            limit = min(limit, global_max_limit)
 
         base_args = {
             "collections": collections,
@@ -736,6 +740,21 @@ async def post_search(
         Raises:
             HTTPException: If there is an error with the cql2_json filter.
         """
+        global_max_limit = int(os.getenv("STAC_GLOBAL_ITEM_MAX_LIMIT", 100))
+        default_limit = int(os.getenv("STAC_DEFAULT_ITEM_LIMIT", 10))
+
+        requested_limit = getattr(search_request, "limit", None)
+
+        if requested_limit is None:
+            limit = default_limit
+        else:
+            limit = requested_limit
+
+        if global_max_limit > 0:
+            limit = min(limit, global_max_limit)
+
+        search_request.limit = limit
+
         base_url = str(request.base_url)
 
         search = self.database.make_search()
@@ -812,10 +831,6 @@ async def post_search(
         if hasattr(search_request, "sortby") and getattr(search_request, "sortby"):
             sort = self.database.populate_sort(getattr(search_request, "sortby"))
 
-        limit = 10
-        if search_request.limit:
-            limit = search_request.limit
-
         # Use token from the request if the model doesn't define it
         token_param = getattr(
             search_request, "token", None

stac_fastapi/tests/api/test_api.py

@@ -1475,47 +1475,41 @@ def create_items(date_prefix: str, start_day: int, count: int) -> dict:
 
 
 @pytest.mark.asyncio
-async def test_collections_limit_env_variable(app_client, txn_client, load_test_data):
-    limit = "5"
-    os.environ["STAC_ITEM_LIMIT"] = limit
-    item = load_test_data("test_collection.json")
+async def test_global_collection_max_limit_set(app_client, txn_client, load_test_data):
+    """Test with global collection max limit set, expect cap the limit"""
+    os.environ["STAC_GLOBAL_COLLECTION_MAX_LIMIT"] = "5"
 
     for i in range(10):
-        test_collection = item.copy()
-        test_collection["id"] = f"test-collection-env-{i}"
-        test_collection["title"] = f"Test Collection Env {i}"
+        test_collection = load_test_data("test_collection.json")
+        test_collection_id = f"test-collection-global-{i}"
+        test_collection["id"] = test_collection_id
         await create_collection(txn_client, test_collection)
 
-    resp = await app_client.get("/collections")
+    resp = await app_client.get("/collections?limit=10")
     assert resp.status_code == 200
     resp_json = resp.json()
-    assert int(limit) == len(resp_json["collections"])
+    assert len(resp_json["collections"]) == 5
 
+    del os.environ["STAC_GLOBAL_COLLECTION_MAX_LIMIT"]
 
-@pytest.mark.asyncio
-async def test_search_collection_limit_env_variable(
-    app_client, txn_client, load_test_data
-):
-    limit = "5"
-    os.environ["STAC_ITEM_LIMIT"] = limit
 
-    test_collection = load_test_data("test_collection.json")
-    test_collection_id = "test-collection-search-limit"
-    test_collection["id"] = test_collection_id
-    await create_collection(txn_client, test_collection)
-
-    item = load_test_data("test_item.json")
-    item["collection"] = test_collection_id
+@pytest.mark.asyncio
+async def test_default_collection_limit(app_client, txn_client, load_test_data):
+    """Test default collection limit set, should use default when no limit provided"""
+    os.environ["STAC_DEFAULT_COLLECTION_LIMIT"] = "5"
 
     for i in range(10):
-        test_item = item.copy()
-        test_item["id"] = f"test-item-search-{i}"
-        await create_item(txn_client, test_item)
+        test_collection = load_test_data("test_collection.json")
+        test_collection_id = f"test-collection-default-{i}"
+        test_collection["id"] = test_collection_id
+        await create_collection(txn_client, test_collection)
 
-    resp = await app_client.get("/search", params={"collections": [test_collection_id]})
+    resp = await app_client.get("/collections")
     assert resp.status_code == 200
     resp_json = resp.json()
-    assert int(limit) == len(resp_json["features"])
+    assert len(resp_json["collections"]) == 5
+
+    del os.environ["STAC_DEFAULT_COLLECTION_LIMIT"]
 
 
 async def test_search_max_item_limit(

stac_fastapi/tests/api/test_api_item_collection.py

@@ -10,14 +10,47 @@
 
 
 @pytest.mark.asyncio
-async def test_item_collection_limit_env_variable(
+async def test_global_item_max_limit_set(app_client, txn_client, load_test_data):
+    """Test with global max limit set for items, expect cap the ?limit parameter"""
+    os.environ["STAC_GLOBAL_ITEM_MAX_LIMIT"] = "5"
+
+    test_collection = load_test_data("test_collection.json")
+    test_collection_id = "test-collection-for-items"
+    test_collection["id"] = test_collection_id
+    await create_collection(txn_client, test_collection)
+
+    item = load_test_data("test_item.json")
+    item["collection"] = test_collection_id
+
+    for i in range(10):
+        test_item = item.copy()
+        test_item["id"] = f"test-item-{i}"
+        await create_item(txn_client, test_item)
+
+    # Test GET /collections/{id}/items with limit parameter
+    resp = await app_client.get(f"/collections/{test_collection_id}/items?limit=10")
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 5
+
+    # Test GET /search with limit parameter
+    resp = await app_client.get(f"/search?collections={test_collection_id}&limit=10")
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 5
+
+    del os.environ["STAC_GLOBAL_ITEM_MAX_LIMIT"]
+
+
+@pytest.mark.asyncio
+async def test_default_item_limit_without_limit_parameter_set(
     app_client, txn_client, load_test_data
 ):
-    limit = "5"
-    os.environ["STAC_ITEM_LIMIT"] = limit
+    """Test default item limit set, should use default when no limit provided"""
+    os.environ["STAC_DEFAULT_ITEM_LIMIT"] = "5"
 
     test_collection = load_test_data("test_collection.json")
-    test_collection_id = "test-collection-items-limit"
+    test_collection_id = "test-collection-items"
     test_collection["id"] = test_collection_id
     await create_collection(txn_client, test_collection)
 
@@ -26,13 +59,20 @@ async def test_item_collection_limit_env_variable(
 
     for i in range(10):
         test_item = item.copy()
-        test_item["id"] = f"test-item-collection-{i}"
+        test_item["id"] = f"test-item-{i}"
         await create_item(txn_client, test_item)
 
     resp = await app_client.get(f"/collections/{test_collection_id}/items")
     assert resp.status_code == 200
     resp_json = resp.json()
-    assert int(limit) == len(resp_json["features"])
+    assert len(resp_json["features"]) == 5
+
+    resp = await app_client.get(f"/search?collections={test_collection_id}")
+    assert resp.status_code == 200
+    resp_json = resp.json()
+    assert len(resp_json["features"]) == 5
+
+    del os.environ["STAC_DEFAULT_ITEM_LIMIT"]
 
 
 @pytest.mark.asyncio