Merge pull request #41 from developmentseed/feature/next-titiler-version

Update for titiler 1.0

Author: vincentsarago

.github/workflows/ci.yml

@@ -19,15 +19,15 @@ on:
   # Run tests on pull requests.
   pull_request:
 env:
-  LATEST_PY_VERSION: '3.13'
+  LATEST_PY_VERSION: '3.14'
 
 
 jobs:
   tests:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', '3.12', '3.13']
+        python-version: ['3.11', '3.12', '3.13', '3.14']
 
     steps:
       - uses: actions/checkout@v5
@@ -71,7 +71,7 @@ jobs:
         with:
           version: "0.9.*" 
           enable-cache: true
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ env.LATEST_PY_VERSION }}
 
       - name: Install dependencies
         run: |

CHANGELOG.md

@@ -2,11 +2,12 @@
 
 ## [Unreleased]
 
+* update titiler requirements to `>=1.0,<1.1`
+
 ## [0.4.0] - 2025-11-06
 
 * switch to `uv` for development
 * switch to `hatch` for python package build-system
-* remove `titiler` metapackage **breaking change**
 * add support for python version 3.13
 * bump minimum python version to 3.11
 * update docker image to python:3.13

Dockerfile

@@ -1,4 +1,4 @@
-ARG PYTHON_VERSION=3.13
+ARG PYTHON_VERSION=3.14
 
 FROM python:${PYTHON_VERSION}
 RUN apt update && apt upgrade -y \

README.md

@@ -38,12 +38,17 @@ python -m pip install -U pip
 python -m pip  install titiler.stacapi
 ```
 
-or from sources and run for development:
+To install from sources and run for development:
+
+We recommand using [`uv`](https://docs.astral.sh/uv) as project manager for development.
+
+See https://docs.astral.sh/uv/getting-started/installation/ for installation 
 
 ```bash
 git clone https://github.com/developmentseed/titiler-stacapi.git
 cd titiler-stacapi
-python -m pip install -e .
+
+uv sync
 ```
 
 ## Launch
@@ -52,12 +57,8 @@ You'll need to have `TITILER_STACAPI_STAC_API_URL` variables set in your environ
 
 ```
 export TITILER_STACAPI_STAC_API_URL=https://api.stac
-```
-
-```
-python -m pip install uvicorn
 
-uvicorn titiler.stacapi.main:app --port 8000
+uv run --extra server uvicorn titiler.stacapi.main:app --port 8000
 ```
 
 ### Using Docker

RELEASING.md

@@ -9,7 +9,7 @@ This is a checklist for releasing a new version of **titiler-stacapi**.
 3. Run [`bump-my-version`](https://callowayproject.github.io/bump-my-version/) to update all titiler's module versions: 
 
     ```
-    bump-my-version bump minor --new-version 0.20.0
+    uv --with bump-my-version --isolated bump-my-version bump minor --new-version 0.20.0
     ```
 
 4. Push your release branch, create a PR, and get approval

docker-compose.yml

@@ -1,8 +1,5 @@
 services:
   api:
-    # At the time of writing, rasterio wheels are not available for arm64 arch
-    # so we force the image to be built with linux/amd64
-    platform: linux/amd64
     build:
       context: .
     ports:

docs/src/custom/application_with_auth.md

@@ -8,6 +8,7 @@ requirements: titiler.stacapi
 ```python
 """TiTiler+stacapi FastAPI application."""
 
+from dataclasses import dataclass, field
 
 from fastapi import Depends, FastAPI
 from fastapi.security import APIKeyHeader
@@ -16,6 +17,7 @@ from starlette.requests import Request
 from typing_extensions import Annotated
 
 import morecantile
+from titiler.core.dependencies import DefaultDependency
 from titiler.core.errors import DEFAULT_STATUS_CODES, add_exception_handlers
 from titiler.core.middleware import CacheControlMiddleware
 from titiler.mosaic.errors import MOSAIC_STATUS_CODES
@@ -31,15 +33,22 @@ stacapi_config = STACAPISettings()
 header_scheme = APIKeyHeader(name="Authorization", description="STAC API Authorization")
 
 
-def STACApiParamsAuth(
-    request: Request,
-    token: Annotated[str, Depends(header_scheme)],
-) -> APIParams:
-    """Return STAC API Parameters."""
-    return APIParams(
-        api_url=request.app.state.stac_url,
-        headers={"Authorization": token},
-    )
+@dataclass(init=False)
+class BackendParams(DefaultDependency):
+    """backend parameters."""
+
+    api_params: APIParams = field(init=False)
+
+    def __init__(self, request: Request, token: Annotated[str, Depends(header_scheme)]):
+        """Initialize BackendParams
+
+        Note: Because we don't want `api_params` to appear in the documentation we use a dataclass with a custom `__init__` method.
+        FastAPI will use the `__init__` method but will exclude Request in the documentation making `api_params` an invisible dependency.
+        """
+        self.api_params = APIParams(
+            url=request.app.state.stac_url,
+            headers={"Authorization": token},
+        )
 
 
 app = FastAPI(
@@ -69,20 +78,17 @@ if settings.cors_origins:
 
 app.add_middleware(CacheControlMiddleware, cachecontrol=settings.cachecontrol)
 
-webmerc = morecantile.tms.get("WebMercatorQuad")
-webmerc.id = "EPSG:3857"
-supported_tms = morecantile.TileMatrixSets({"EPSG:3857": webmerc})
+webmerc = morecantile.tms.get("WebMercatorQuad").model_dump()
+webmerc["id"] = "EPSG3857"
+supported_tms = morecantile.TileMatrixSets({"EPSG3857": morecantile.TileMatrixSet.model_validate(webmerc)})
 
 ###############################################################################
 # OGC WMTS Endpoints
 wmts = OGCWMTSFactory(
-    path_dependency=STACApiParamsAuth,
+    backend_dependency=BackendParams,
     supported_tms=supported_tms,
 )
 
-app.include_router(
-    wmts.router,
-    tags=["Web Map Tile Service"],
-)
+app.include_router(wmts.router, tags=["Web Map Tile Service"])
 
 ```

docs/src/endpoints/collections_endpoints.md

@@ -4,10 +4,17 @@
 
 | Method | URL                                                                              | Output                                  | Description
 | ------ | ---------------------------------------------------------------------------------|-----------------------------------------|--------------
-| `GET`  | `/collections/{collection_id}/tiles/{TileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]` | image/bin                               | Create a web map tile image for a collection and a tile index
-| `GET`  | `/collections/{collection_id}/{TileMatrixSetId}/tilejson.json`                           | JSON ([TileJSON][tilejson_model])       | Return a Mapbox TileJSON document
-| `GET`  | `/collections/{collection_id}/{TileMatrixSetId}/WMTSCapabilities.xml`                    | XML                                     | return OGC WMTS Get Capabilities
-| `GET`  | `/collections/{collection_id}/{TileMatrixSetId}/map`                                     | HTML                                    | simple map viewer
+| `GET`  | `/collections/{collection_id}/info`                                              | JSON                                    | return mosaic's basic info
+| `GET`  | `/collections/{collection_id}/info.geojson`                                      | GeoJSON                                 | return mosaic's basic info as a GeoJSON feature
+| `GET`  | `/collections/{collection_id}/tiles`                                             | JSON                                    | List of OGC Tilesets available
+| `GET`  | `/collections/{collection_id}/tiles/{tileMatrixSetId}`                           | JSON                                    | OGC Tileset metadata
+| `GET`  | `/collections/{collection_id}/tiles/{TileMatrixSetId}/{z}/{x}/{y}[@{scale}x][.{format}]` | image/bin                       | Create a web map tile image for a collection and a tile index
+| `GET`  | `/collections/{collection_id}/{TileMatrixSetId}/tilejson.json`                           | JSON ([TileJSON][tilejson_model]) | Return a Mapbox TileJSON document
+| `GET`  | `/collections/{collection_id}/{TileMatrixSetId}/map.html`                                | HTML                              | simple map viewer
+| `GET`  | `/collections/{collection_id}/point/{lon},{lat}`                                            | JSON      | return pixel value from a mosaic assets
+| `GET`  | `/collections/{collection_id}/bbox/{minx},{miny},{maxx},{maxy}/assets`                      | JSON      | return list of assets intersecting a bounding box
+| `GET`  | `/collections/{collection_id}/point/{lon},{lat}/assets`                                     | JSON      | return list of assets intersecting a point
+| `GET`  | `/collections/{collection_id}/tiles/{tileMatrixSetId}/{z}/{x}/{y}/assets`                   | JSON      | return list of assets intersecting a XYZ tile
 
 ### Tiles
 
@@ -46,6 +53,9 @@
     - **ids** (str): Comma (',') delimited list of IDS.
     - **bbox** (str): Comma (',') delimited BoundingBox (not used in the search query, but usefull to limit the bbox of the mosaic).
     - **datetime** (str): Datetime filter for the Search Query following `RFC 3339` format (https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/implementation.md#datetime-parameter-handling)
+    - **filter** (str): A CQL2 filter expression for filtering items.
+    - **filter-lang** (str): CQL2 Language (cql2-text, cql2-json). Defaults to cql2-text.
+    - **sortby** (str): An array of property names, prefixed by either '+' for ascending or '-' for descending. If no prefix is provided, '+' is assumed.
     - **limit** (int): The maximum number of results to return (page size). Defaults to 10.
     - **max_items** (int): The maximum number of items to used in a mosaic. Defaults to 100.
 
@@ -94,6 +104,9 @@ Example:
     - **ids** (str): Comma (',') delimited list of IDS.
     - **bbox** (str): Comma (',') delimited BoundingBox (not used in the search query, but usefull to limit the bbox of the mosaic).
     - **datetime** (str): Datetime filter for the Search Query following `RFC 3339` format (https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/implementation.md#datetime-parameter-handling)
+    - **filter** (str): A CQL2 filter expression for filtering items.
+    - **filter-lang** (str): CQL2 Language (cql2-text, cql2-json). Defaults to cql2-text.
+    - **sortby** (str): An array of property names, prefixed by either '+' for ascending or '-' for descending. If no prefix is provided, '+' is assumed.
     - **limit** (int): The maximum number of results to return (page size). Defaults to 10.
     - **max_items** (int): The maximum number of items to used in a mosaic. Defaults to 100.
 
@@ -106,29 +119,4 @@ Example:
 - `https://myendpoint/collections/my-collection/WebMercatorQuad/tilejson.json?assets=B01&tile_format=png`
 - `https://myendpoint/collections/my-collection/WorldCRS84Quad/tilejson.json?assets=B01&tile_scale=2`
 
-
-### WMTS
-
-`:endpoint:/collections/{collection_id}/{TileMatrixSetId}/WMTSCapabilities.xml`
-
-- PathParams:
-    - **collection_id**: STAC Collection Identifier.
-    - **TileMatrixSetId**: TileMatrixSet name (e.g `WebMercatorQuad`).
-
-- QueryParams:
-    - **tile_format**: Output image format, default is set to PNG.
-    - **tile_scale**: Tile size scale, default is set to 1 (256x256). OPTIONAL
-    - **minzoom**: Overwrite default minzoom. OPTIONAL
-    - **maxzoom**: Overwrite default maxzoom. OPTIONAL
-
-!!! important
-    additional query-parameters will be forwarded to the `tile` URL. If no `defaults` mosaic metadata, **assets** OR **expression** will be required
-
-Example:
-
-- `https://myendpoint/collections/my-collection/WebMercatorQuad/WMTSCapabilities.xml?assets=B01`
-- `https://myendpoint/collections/my-collection/WebMercatorQuad/WMTSCapabilities.xml?assets=B01&tile_format=png`
-- `https://myendpoint/collections/my-collection/WorldCRS84Quad/WMTSCapabilities.xml?assets=B01&tile_scale=2`
-
-
-[tilejson_model]: https://github.com/developmentseed/titiler/blob/2335048a407f17127099cbbc6c14e1328852d619/src/titiler/core/titiler/core/models/mapbox.py#L16-L38
+[tilejson_model]: https://github.com/developmentseed/titiler/blob/2335048a407f17127099cbbc6c14e1328852d619/src/titiler/core/titiler/core/models/mapbox.py#L16-L38

docs/src/endpoints/items_endpoints.md

@@ -4,17 +4,17 @@ The `Item` endpoints are created using TiTiler's [MultiBaseTilerFactory](https:/
 
 | Method | URL                                                                  | Output                                           | Description
 | ------ | -------------------------------------------------------------------- |------------------------------------------------- |--------------
-| `GET`  | `/collections/{collection_id}/items/{item_id}/bounds`                                                       | JSON ([Bounds][bounds_model])                    | return dataset's bounds
-| `GET`  | `/collections/{collection_id}/items/{item_id}/assets`                                                       | JSON                                             | return the list of available assets
 | `GET`  | `/collections/{collection_id}/items/{item_id}/info`                                                         | JSON ([Info][multiinfo_model])                   | return assets basic info
 | `GET`  | `/collections/{collection_id}/items/{item_id}/info.geojson`                                                 | GeoJSON ([InfoGeoJSON][multiinfo_geojson_model]) | return assets basic info as a GeoJSON feature
+| `GET`  | `/collections/{collection_id}/items/{item_id}/assets`                                                       | JSON                                             | return the list of available assets
 | `GET`  | `/collections/{collection_id}/items/{item_id}/asset_statistics`                                             | JSON ([Statistics][multistats_model])            | return per asset statistics
 | `GET`  | `/collections/{collection_id}/items/{item_id}/statistics`                                                   | JSON ([Statistics][stats_model])                 | return assets statistics (merged)
 | `POST` | `/collections/{collection_id}/items/{item_id}/statistics`                                                   | GeoJSON ([Statistics][multistats_geojson_model]) | return assets statistics for a GeoJSON (merged)
+| `GET`  | `/collections/{collection_id}/items/{item_id}/tiles`                                                        | JSON                                             | List of OGC Tilesets available
+| `GET`  | `/collections/{collection_id}/items/{item_id}/tiles/{tileMatrixSetId}`                                      | JSON                                             | OGC Tileset metadata
 | `GET`  | `/collections/{collection_id}/items/{item_id}/tiles[/{TileMatrixSetId}]/{z}/{x}/{y}[@{scale}x][.{format}]`  | image/bin                                        | create a web map tile image from assets
 | `GET`  | `/collections/{collection_id}/items/{item_id}[/{TileMatrixSetId}]/tilejson.json`                            | JSON ([TileJSON][tilejson_model])                | return a Mapbox TileJSON document
-| `GET`  | `/collections/{collection_id}/items/{item_id}[/{TileMatrixSetId}]/WMTSCapabilities.xml`                     | XML                                              | return OGC WMTS Get Capabilities
-| `GET`  | `/collections/{collection_id}/items/{item_id}[/{TileMatrixSetId}]/map`                                      | HTML                                             | simple map viewer
+| `GET`  | `/collections/{collection_id}/items/{item_id}[/{TileMatrixSetId}]/map.html`                                 | HTML                                             | simple map viewer
 | `GET`  | `/collections/{collection_id}/items/{item_id}/point/{lon},{lat}`                                            | JSON ([Point][multipoint_model])                 | return pixel values from assets
 | `GET`  | `/collections/{collection_id}/items/{item_id}/preview[.{format}]`                                           | image/bin                                        | create a preview image from assets
 | `GET`  | `/collections/{collection_id}/items/{item_id}/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                        | create an image from part of assets
@@ -265,18 +265,6 @@ Example:
 - `https://myendpoint/collections/mycollection/items/oneitem/tilejson.json?assets=B01&tile_format=png`
 - `https://myendpoint/collections/mycollection/items/oneitem/WorldCRS84Quad/tilejson.json?tile_scale=2&expression=B01/B02&asset_as_band=True`
 
-### Bounds
-
-`:endpoint:/collections/{collection_id}/items/{item_id}/bounds` - Return the bounds of the STAC item.
-
-- PathParams:
-    - **collection_id** (str): STAC Collection Identifier.
-    - **item_id** (str): STAC Item Identifier.
-
-Example:
-
-- `https://myendpoint/collections/mycollection/items/oneitem/bounds`
-
 
 ### Info
 

docs/src/endpoints/ogc_wmts_endpoints.md

@@ -48,7 +48,7 @@ Example:
 `:endpoint:/layers/{LAYER}/{STYLE}/{TIME}/{TileMatrixSet}/{TileMatrix}/{TileCol}/{TileRow}.{FORMAT}`
 
 - PathParams:
-    - **Layer** (str): Layer identifier
+    - **Layer** (str): Layer identifier (collection_id)
     - **Style** (str): Style identifier
     - **Time** (str): TIME Dimension
     - **TileMatrixSet** (str): TileMatrixSet identifier
@@ -59,4 +59,4 @@ Example:
 
 Example:
 
-- `https://myendpoint/MyLayer/default/2023-01-01/WebMercatorQuad/0/0/0.png
+- `https://myendpoint/layers/my-collection/default/2023-01-01/WebMercatorQuad/0/0/0.png`