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,

stac_fastapi/tests/api/test_api.py

@@ -1475,9 +1475,11 @@ 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):
+async def test_collections_limit_env_variable(
+    app_client, txn_client, load_test_data, monkeypatch
+):
     limit = "5"
-    os.environ["STAC_ITEM_LIMIT"] = limit
+    os.environ["STAC_DEFAULT_COLLECTION_LIMIT"] = limit
     item = load_test_data("test_collection.json")
 
     for i in range(10):
@@ -1497,7 +1499,7 @@ async def test_search_collection_limit_env_variable(
     app_client, txn_client, load_test_data
 ):
     limit = "5"
-    os.environ["STAC_ITEM_LIMIT"] = limit
+    os.environ["STAC_DEFAULT_ITEM_LIMIT"] = limit
 
     test_collection = load_test_data("test_collection.json")
     test_collection_id = "test-collection-search-limit"

stac_fastapi/tests/api/test_api_item_collection.py

@@ -14,7 +14,7 @@ async def test_item_collection_limit_env_variable(
     app_client, txn_client, load_test_data
 ):
     limit = "5"
-    os.environ["STAC_ITEM_LIMIT"] = limit
+    os.environ["STAC_DEFAULT_ITEM_LIMIT"] = limit
 
     test_collection = load_test_data("test_collection.json")
     test_collection_id = "test-collection-items-limit"