Merge pull request #57 from developmentseed/feat/add-items-env-settings

add: env settings to configure items search

Author: vincentsarago

.pre-commit-config.yaml

@@ -1,24 +1,24 @@
 repos:
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.24
+    rev: v0.25
     hooks:
       - id: validate-pyproject
 
   - repo: https://github.com/PyCQA/isort
-    rev: 5.12.0
+    rev: 8.0.1
     hooks:
       - id: isort
         language_version: python
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.4
+    rev: v0.15.9
     hooks:
       - id: ruff
         args: ["--fix"]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.2
+    rev: v1.20.0
     hooks:
       - id: mypy
         language_version: python

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-04-07
+
+* add: env settings to configure MaxItems and ItemsPerPage options for STAC API Backend
+    - `TITILER_STACAPI_ITEMS_PER_PAGE`: set number of items `per-page` returned for Search request (defaults to 10)
+    - `TITILER_STACAPI_MAX_ITEMS`: set max items returned by a Search request (defaults to 100)
+
 ## [2.0.0] - 2026-03-16
 
 * change: titiler-* requirements to >=2.0,<2.1

titiler/stacapi/backend.py

@@ -23,10 +23,11 @@
 
 from titiler.stacapi.dependencies import APIParams, Search
 from titiler.stacapi.reader import Item, SimpleSTACReader
-from titiler.stacapi.settings import CacheSettings, RetrySettings
+from titiler.stacapi.settings import CacheSettings, ItemsSettings, RetrySettings
 
 cache_config = CacheSettings()
 retry_config = RetrySettings()
+items_config = ItemsSettings()
 
 ttl_cache = TTLCache(maxsize=cache_config.maxsize, ttl=cache_config.ttl)  # type: ignore
 
@@ -138,8 +139,8 @@ def get_assets(
             **self.input,
             "method": "GET" if self.input.get("filter") else "POST",
             "sortby": sortby,
-            "limit": limit or 10,
-            "max_items": max_items or 100,
+            "limit": limit or items_config.items_per_page,
+            "max_items": max_items or items_config.max_items,
         }
         fields = fields or ["assets", "id", "bbox", "collection"]
 

titiler/stacapi/dependencies.py

@@ -15,12 +15,13 @@
 from urllib3 import Retry
 
 from titiler.core.dependencies import DefaultDependency
-from titiler.stacapi.settings import CacheSettings, RetrySettings
+from titiler.stacapi.settings import CacheSettings, ItemsSettings, RetrySettings
 
 ResponseType = Literal["json", "html"]
 
 cache_config = CacheSettings()
 retry_config = RetrySettings()
+items_config = ItemsSettings()
 
 
 class APIParams(TypedDict):
@@ -286,12 +287,16 @@ class STACAPIExtensionParams(DefaultDependency):
     ] = None
     limit: Annotated[
         int | None,
-        Query(description="Limit the number of items per page search (default: 10)"),
-    ] = 10
+        Query(
+            description=f"Limit the number of items per page search (default: {items_config.items_per_page})"
+        ),
+    ] = None
     max_items: Annotated[
         int | None,
-        Query(description="Limit the number of total items (default: 100)"),
-    ] = 100
+        Query(
+            description=f"Limit the number of total items (default: {items_config.max_items})"
+        ),
+    ] = None
 
     def __post_init__(self):
         """Post Init."""

titiler/stacapi/factory.py

@@ -191,9 +191,9 @@ def get_layer_from_collections(  # noqa: C901
                     layer["bbox"] = tuple(spatial_extent.bboxes[0])
 
                 if supported_tms:
-                    tilematrixsets: dict[str, tuple[int, int] | None] = {
-                        tms_id: None for tms_id in supported_tms.list()
-                    }
+                    tilematrixsets: dict[str, tuple[int, int] | None] = dict.fromkeys(
+                        supported_tms.list()
+                    )
                     for tms_id, zooms in tilematrixsets.items():
                         if zooms := render_tilematrixsets.get(tms_id):
                             tilematrixsets[tms_id] = zooms

titiler/stacapi/settings.py

@@ -83,3 +83,16 @@ class STACAPISettings(BaseSettings):
         "env_file": ".env",
         "extra": "ignore",
     }
+
+
+class ItemsSettings(BaseSettings):
+    """STAC API Items settings"""
+
+    max_items: int = 100
+    items_per_page: int = 10
+
+    model_config = {
+        "env_prefix": "TITILER_STACAPI_",
+        "env_file": ".env",
+        "extra": "ignore",
+    }