geovisio 2.8.1__py3-none-any.whl → 2.10.0__py3-none-any.whl

geovisio/web/collections.py

@@ -1,23 +1,24 @@
 from enum import Enum
-from attr import dataclass
 from geovisio import errors, utils, db
 from geovisio.utils import auth, sequences
 from geovisio.utils.params import validation_error
-from geovisio.utils.semantics import SemanticTagUpdate, Entity, EntityType, update_tags
+from geovisio.utils.semantics import Entity, EntityType, update_tags
+from geovisio.utils.tags import SemanticTagUpdate
 from geovisio.web.params import (
     parse_datetime,
     parse_datetime_interval,
     parse_bbox,
-    parse_filter,
-    parse_sortby,
+    parse_collection_filter,
+    parse_collection_sortby,
     parse_collections_limit,
 )
 from geovisio.utils.sequences import (
     STAC_FIELD_MAPPINGS,
     CollectionsRequest,
     get_collections,
+    get_dataset_bounds,
 )
-from geovisio.utils.fields import SortBy, SortByField, SQLDirection, Bounds, BBox
+from geovisio.utils.fields import SortBy, SortByField, SQLDirection, BBox, parse_relative_heading
 from geovisio.web.rss import dbSequencesToGeoRSS
 from psycopg.rows import dict_row
 from psycopg.sql import SQL
@@ -94,7 +95,7 @@ def dbSequenceToStacCollection(dbSeq, description="A sequence of geolocated pict
             "title": str(dbSeq["name"]),
             "description": description,
             "keywords": ["pictures", str(dbSeq["name"])],
-            "semantics": dbSeq["semantics"] if "semantics" in dbSeq else None,
+            "semantics": dbSeq.get("semantics", []),
             "license": current_app.config["API_PICTURES_LICENSE_SPDX_ID"],
             "created": dbTsToStac(dbSeq["created"]),
             "updated": dbTsToStac(dbSeq.get("updated")),
@@ -157,6 +158,16 @@ def dbSequenceToStacCollection(dbSeq, description="A sequence of geolocated pict
                         "href": url_for("stac_collections.getCollection", _external=True, collectionId=dbSeq["id"]),
                     },
                     get_license_link(),
+                    (
+                        {
+                            "rel": "upload_set",
+                            "type": "application/json",
+                            "title": "Link to the upload set",
+                            "href": url_for("upload_set.getUploadSet", _external=True, upload_set_id=dbSeq["upload_set_id"]),
+                        }
+                        if dbSeq.get("upload_set_id")
+                        else None
+                    ),
                 ]
             ),
         }
@@ -244,16 +255,22 @@ def getAllCollections():
         format = "rss"
 
     # Sort-by parameter
-    sortBy = parse_sortby(request.args.get("sortby"))
+    sortBy = parse_collection_sortby(request.args.get("sortby"))
     if not sortBy:
         direction = SQLDirection.DESC if format == "rss" else SQLDirection.ASC
         sortBy = SortBy(fields=[SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=direction)])
+    # we always add the creation date fields in the sort list (after the selected ones), this will we'll get the `created` bounds of the dataset
+    # we'll also get
+    if not any(s.field == STAC_FIELD_MAPPINGS["created"] for s in sortBy.fields):
+        sortBy.fields.append(SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.ASC))
+    if not any(s.field == STAC_FIELD_MAPPINGS["id"] for s in sortBy.fields):
+        sortBy.fields.append(SortByField(field=STAC_FIELD_MAPPINGS["id"], direction=SQLDirection.ASC))
 
     collection_request = CollectionsRequest(sort_by=sortBy)
 
     # Filter parameter
-    collection_request.user_filter = parse_filter(request.args.get("filter"))
-    collection_request.pagination_filter = parse_filter(request.args.get("page"))
+    collection_request.user_filter = parse_collection_filter(request.args.get("filter"))
+    collection_request.pagination_filter = parse_collection_filter(request.args.get("page"))
 
     # Limit parameter
     collection_request.limit = parse_collections_limit(request.args.get("limit"))
@@ -298,14 +315,14 @@ def getAllCollections():
         },
     ]
 
-    with db.cursor(current_app, row_factory=dict_row) as cursor:
-        stats = cursor.execute("SELECT min(inserted_at) as min, max(inserted_at) as max FROM sequences").fetchone()
-        if stats is None:
+    with db.conn(current_app) as conn:
+        datasetBounds = get_dataset_bounds(conn, collection_request.sort_by, additional_filters=collection_request.user_filter)
+        if datasetBounds is None:
             return ({"collections": [], "links": links}, 200, {"Content-Type": "application/json"})
-        datasetBounds = Bounds(min=stats["min"], max=stats["max"])
-        if collection_request.created_after and collection_request.created_after > datasetBounds.max:
+        creation_date_index = collection_request.sort_by.get_field_index("created")
+        if collection_request.created_after and collection_request.created_after > datasetBounds.last[creation_date_index]:
             raise errors.InvalidAPIUsage(_("There is no collection created after %(d)s", d=collection_request.created_after))
-        if collection_request.created_before and collection_request.created_before < datasetBounds.min:
+        if collection_request.created_before and collection_request.created_before < datasetBounds.first[creation_date_index]:
             raise errors.InvalidAPIUsage(_("There is no collection created before %(d)s", d=collection_request.created_before))
 
     db_collections = get_collections(collection_request)
@@ -322,10 +339,9 @@ def getAllCollections():
     pagination_links = sequences.get_pagination_links(
         route="stac_collections.getAllCollections",
         routeArgs={"limit": collection_request.limit},
-        field=sortBy.fields[0].field.stac,
-        direction=sortBy.fields[0].direction,
+        sortBy=sortBy,
         datasetBounds=datasetBounds,
-        dataBounds=db_collections.query_first_order_bounds,
+        dataBounds=db_collections.query_bounds,
         additional_filters=additional_filters,
     )
 
@@ -374,8 +390,7 @@ def getCollection(collectionId):
 
     record = db.fetchone(
         current_app,
-        """
-            SELECT
+        """SELECT
                 s.id,
                 s.metadata->>'title' AS name,
                 ST_XMin(s.bbox) AS minx,
@@ -385,6 +400,7 @@ def getCollection(collectionId):
                 s.status AS status,
                 accounts.name AS account_name,
                 s.account_id AS account_id,
+                s.upload_set_id,
                 s.inserted_at AS created,
                 s.updated_at AS updated,
                 s.current_sort AS current_sort,
@@ -396,16 +412,16 @@ def getCollection(collectionId):
                 ROUND(ST_Length(s.geom::geography)) / 1000 as length_km,
                 s.computed_h_pixel_density,
                 s.computed_gps_accuracy,
-                t.semantics
+                COALESCE(seq_sem.semantics, '[]'::json) AS semantics
             FROM sequences s
             LEFT JOIN (
                 SELECT sequence_id, json_agg(json_strip_nulls(json_build_object(
                     'key', key,
                     'value', value
-                ))) AS semantics
+                )) ORDER BY key, value) AS semantics
                 FROM sequences_semantics
                 GROUP BY sequence_id
-            ) t ON t.sequence_id = s.id
+            ) seq_sem ON seq_sem.sequence_id = s.id
             JOIN accounts ON s.account_id = accounts.id, (
                 SELECT
                     array_agg(DISTINCT jsonb_build_object(
@@ -494,6 +510,10 @@ def getCollectionThumbnail(collectionId):
 @auth.login_required_by_setting("API_FORCE_AUTH_ON_UPLOAD")
 def postCollection(account=None):
     """Create a new sequence
+
+    Note that this is the legacy API, upload should be done using the [UploadSet](#UploadSet) endpoints if possible.
+
+    Using an upload set makes it possible to handle more use cases like dispatching pictures into several collections, removing capture duplicates, parralele upload, ...
     ---
     tags:
         - Upload
@@ -503,7 +523,7 @@ def postCollection(account=None):
           required: false
           schema:
             type: string
-          description: An explicit User-Agent value is prefered if you create a production-ready tool, formatted like "PanoramaxCLI/1.0"
+          description: An explicit User-Agent value is preferred if you create a production-ready tool, formatted like "PanoramaxCLI/1.0"
     requestBody:
         content:
             application/json:
@@ -557,7 +577,7 @@ class PatchCollectionParameter(BaseModel):
     """Parameters used to add an item to an UploadSet"""
 
     relative_heading: Optional[int] = None
-    """The relative heading (in degrees), offset based on movement path (0° = looking forward, -90° = looking left, 90° = looking right). Headings are unchanged if this parameter is not set."""
+    """The relative heading (in degrees), offset based on movement path (0° = looking forward, -90° = looking left, 90° = looking right). For single picture collections, 0° is heading north). Headings are unchanged if this parameter is not set."""
     visible: Optional[bool] = None
     """Should the sequence be publicly visible ?"""
     title: Optional[str] = Field(max_length=250, default=None)
@@ -602,15 +622,7 @@ If unset, sort order is unchanged."""
     @field_validator("relative_heading", mode="before")
     @classmethod
     def parse_relative_heading(cls, value):
-        try:
-            relHeading = int(value)
-            if relHeading < -180 or relHeading > 180:
-                raise ValueError()
-            return relHeading
-        except ValueError:
-            raise errors.InvalidAPIUsage(
-                _("Relative heading is not valid, should be an integer in degrees from -180 to 180"), status_code=400
-            )
+        return parse_relative_heading(value)
 
     def has_only_semantics_updates(self):
         return self.model_fields_set == {"semantics"}
@@ -629,7 +641,7 @@ def patchCollection(collectionId, account):
     ---
     tags:
         - Editing
-        - Tags
+        - Semantics
     parameters:
         - name: collectionId
           in: path
@@ -749,13 +761,7 @@ def patchCollection(collectionId, account):
                     sqlUpdates.append(SQL("last_account_to_edit = %(account)s"))
 
                     cursor.execute(
-                        SQL(
-                            """
-                            UPDATE sequences
-                            SET {updates}
-                            WHERE id = %(id)s
-                            """
-                        ).format(updates=SQL(", ").join(sqlUpdates)),
+                        SQL("UPDATE sequences SET {updates} WHERE id = %(id)s").format(updates=SQL(", ").join(sqlUpdates)),
                         sqlParams,
                     )
 
@@ -924,7 +930,12 @@ def send_collections_as_csv(collection_request: CollectionsRequest):
         raise errors.InvalidAPIUsage(_("CSV export does not support pagination"), status_code=400)
     if collection_request.filters():
         raise errors.InvalidAPIUsage(_("CSV export does not support filters"), status_code=400)
-    if collection_request.sort_by != SortBy(fields=[SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.DESC)]):
+    if collection_request.sort_by != SortBy(
+        fields=[
+            SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.DESC),
+            SortByField(field=STAC_FIELD_MAPPINGS["id"], direction=SQLDirection.ASC),
+        ]
+    ):
         raise errors.InvalidAPIUsage(_("CSV export does not support sorting by anything but creation date"), status_code=400)
 
     def generate_csv():
@@ -957,7 +968,7 @@ SELECT
     s.computed_gps_accuracy AS computed_gps_accuracy
 FROM sequences s 
 WHERE {filter}
-ORDER BY s.inserted_at DESC
+ORDER BY s.inserted_at DESC, id ASC
 ) TO STDOUT CSV HEADER"""
                 ).format(filter=SQL(" AND ").join(filters)),
                 params,
@@ -966,7 +977,7 @@ ORDER BY s.inserted_at DESC
                 for a in copy:
                     yield bytes(a)
 
-    return stream_with_context(generate_csv()), {"Content-Disposition": "attachment"}
+    return stream_with_context(generate_csv()), {"Content-Type": "text/csv", "Content-Disposition": "attachment"}
 
 
 @bp.route("/users/<uuid:userId>/collection")
@@ -1029,17 +1040,21 @@ def getUserCollection(userId, userIdMatchesAccount=False):
         format = "csv"
 
     # Sort-by parameter
-    sortBy = parse_sortby(request.args.get("sortby"))
+    sortBy = parse_collection_sortby(request.args.get("sortby"))
     if not sortBy:
         sortBy = SortBy(fields=[SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.DESC)])
 
+    if not any(s.field == STAC_FIELD_MAPPINGS["created"] for s in sortBy.fields):
+        sortBy.fields.append(SortByField(field=STAC_FIELD_MAPPINGS["created"], direction=SQLDirection.ASC))
+    if not any(s.field == STAC_FIELD_MAPPINGS["id"] for s in sortBy.fields):
+        sortBy.fields.append(SortByField(field=STAC_FIELD_MAPPINGS["id"], direction=SQLDirection.ASC))
     collection_request = CollectionsRequest(sort_by=sortBy, userOwnsAllCollections=userIdMatchesAccount)
 
     # Filter parameter
-    collection_request.user_filter = parse_filter(request.args.get("filter"))
+    collection_request.user_filter = parse_collection_filter(request.args.get("filter"))
 
     # Filters added by the pagination
-    collection_request.pagination_filter = parse_filter(request.args.get("page"))
+    collection_request.pagination_filter = parse_collection_filter(request.args.get("page"))
 
     # Limit parameter
     # if not specified, the default with CSV it 1000. if there are more, the paginated API should be used
@@ -1095,8 +1110,6 @@ def getUserCollection(userId, userIdMatchesAccount=False):
                 MAX(LEAST(90, ST_YMax(s.bbox))) AS maxy,
                 MIN(s.inserted_at) AS created,
                 MAX(s.updated_at) AS updated,
-                MIN({order_column}) AS min_order,
-                MAX({order_column}) AS max_order,
                 ROUND(SUM(ST_Length(s.geom::geography))) / 1000 AS length_km
             FROM sequences s
             WHERE {filter}
@@ -1115,6 +1128,13 @@ def getUserCollection(userId, userIdMatchesAccount=False):
             else:
                 raise errors.InvalidAPIUsage(_("No matching sequences found"), 404)
 
+        datasetBounds = get_dataset_bounds(
+            cursor.connection,
+            collection_request.sort_by,
+            additional_filters=SQL(" AND ").join(meta_filter),
+            additional_filters_params={"account": userId},
+        )
+
     collections = get_collections(collection_request)
 
     sequences_links = [
@@ -1164,10 +1184,9 @@ def getUserCollection(userId, userIdMatchesAccount=False):
     pagination_links = sequences.get_pagination_links(
         route="stac_collections.getUserCollection",
         routeArgs={"userId": str(userId), "limit": collection_request.limit},
-        field=sortBy.fields[0].field.stac,
-        direction=sortBy.fields[0].direction,
-        datasetBounds=Bounds(min=meta_collection["min_order"], max=meta_collection["max_order"]),
-        dataBounds=collections.query_first_order_bounds,
+        sortBy=sortBy,
+        datasetBounds=datasetBounds,
+        dataBounds=collections.query_bounds,
         additional_filters=additional_filters,
     )
 

geovisio/web/configuration.py

@@ -1,15 +1,20 @@
 import flask
 from typing import Dict, Any
-from flask import jsonify
+from flask import jsonify, current_app
 from flask_babel import get_locale
 from geovisio.web.utils import get_api_version
+from geovisio.utils import db
+from psycopg.rows import class_row
+from typing import Optional
+from pydantic import BaseModel, Field, ConfigDict, field_serializer
+import datetime
 
 bp = flask.Blueprint("configuration", __name__, url_prefix="/api")
 
 
 @bp.route("/configuration")
 def configuration():
-    """Return instance configuration informations
+    """Return instance configuration information
     ---
     tags:
         - Metadata
@@ -29,13 +34,14 @@ def configuration():
             "name": _get_translated(apiSum.name, userLang),
             "description": _get_translated(apiSum.description, userLang),
             "geo_coverage": _get_translated(apiSum.geo_coverage, userLang),
-            "logo": apiSum.logo,
+            "logo": str(apiSum.logo),
             "color": str(apiSum.color),
             "email": apiSum.email,
             "auth": _auth_configuration(),
             "license": _license_configuration(),
             "version": get_api_version(),
             "pages": _get_pages(),
+            "defaults": _get_default_values(),
         }
     )
 
@@ -53,6 +59,7 @@ def _auth_configuration():
         return {
             "enabled": True,
             "user_profile": {"url": auth.oauth_provider.user_profile_page_url()},
+            "registration_is_open": flask.current_app.config["API_REGISTRATION_IS_OPEN"],
             "enforce_tos_acceptance": flask.current_app.config["API_ENFORCE_TOS_ACCEPTANCE"],
         }
 
@@ -66,9 +73,23 @@ def _license_configuration():
 
 
 def _get_pages():
-    from geovisio.utils import db
-    from flask import current_app
 
     pages = db.fetchall(current_app, "SELECT distinct(name) FROM pages")
 
     return [p[0] for p in pages]
+
+
+class Config(BaseModel):
+    collaborative_metadata: Optional[bool]
+    split_distance: Optional[int] = Field(validation_alias="default_split_distance")
+    split_time: Optional[datetime.timedelta] = Field(validation_alias="default_split_time")
+    duplicate_distance: Optional[float] = Field(validation_alias="default_duplicate_distance")
+    duplicate_rotation: Optional[int] = Field(validation_alias="default_duplicate_rotation")
+
+    @field_serializer("split_time")
+    def split_time_to_s(self, s: datetime.timedelta, _):
+        return s.total_seconds()
+
+
+def _get_default_values():
+    return db.fetchone(current_app, "SELECT * FROM configurations", row_factory=class_row(Config)).model_dump()

geovisio/web/docs.py

@@ -1,5 +1,10 @@
-from geovisio.web import annotations, collections, items, prepare, users, utils, upload_set, reports, excluded_areas, pages
-from geovisio.utils import upload_set as upload_set_utils, reports as reports_utils, excluded_areas as excluded_areas_utils
+from geovisio.web import collections, items, prepare, users, utils, upload_set, reports, excluded_areas, pages, annotations
+from geovisio.utils import (
+    upload_set as upload_set_utils,
+    reports as reports_utils,
+    excluded_areas as excluded_areas_utils,
+    annotations as annotations_utils,
+)
 from importlib import metadata
 import re
 
@@ -240,6 +245,12 @@ Note that you may not rely only on these ID that could change through time.
             "PreparationParameter": prepare.PreparationParameter.model_json_schema(
                 ref_template="#/components/schemas/PreparationParameter/$defs/{model}", mode="serialization"
             ),
+            "GeovisioPostToken": {
+                "type": "object",
+                "properties": {
+                    "description": {"type": "string", "description": "optional description of the token"},
+                },
+            },
             "GeoVisioPostUploadSet": upload_set.UploadSetCreationParameter.model_json_schema(
                 ref_template="#/components/schemas/GeoVisioPostUploadSet/$defs/{model}", mode="serialization"
             ),
@@ -258,6 +269,9 @@ Note that you may not rely only on these ID that could change through time.
             "GeoVisioUploadSetFiles": upload_set_utils.UploadSetFiles.model_json_schema(
                 ref_template="#/components/schemas/GeoVisioUploadSetFiles/$defs/{model}", mode="serialization"
             ),
+            "UploadSetUpdateParameter": upload_set.UploadSetUpdateParameter.model_json_schema(
+                ref_template="#/components/schemas/UploadSetUpdateParameter/$defs/{model}", mode="serialization"
+            ),
             "GeoVisioCollectionOfCollection": {
                 "allOf": [
                     {"$ref": "#/components/schemas/STACCollection"},
@@ -295,7 +309,7 @@ Note that you may not rely only on these ID that could change through time.
             },
             "GeoVisioCSVCollections": {
                 "type": "string",
-                "descrition": f"""CSV file containing the collections.
+                "description": f"""CSV file containing the collections.
 
 The CSV headers will be:
 * id: ID of the collection
@@ -456,12 +470,32 @@ The CSV headers will be:
                                     "datetimetz": {
                                         "type": "string",
                                         "format": "date-time",
-                                        "title": "Date & time with original timezone information",
+                                        "title": "Date & time of the picture (when it was captured).",
+                                    },
+                                    "datetimetz": {
+                                        "type": "string",
+                                        "format": "date-time",
+                                        "title": "Date & time of the picture (when it was captured) with original timezone information",
+                                    },
+                                    "created": {
+                                        "type": "string",
+                                        "format": "date-time",
+                                        "title": "Date & time of picture upload",
+                                    },
+                                    "updated": {
+                                        "type": "string",
+                                        "format": "date-time",
+                                        "title": "Date & time of picture's metadata update",
                                     },
                                     "geovisio:status": {"$ref": "#/components/schemas/GeoVisioItemStatus"},
                                     "geovisio:producer": {"type": "string"},
                                     "geovisio:image": {"type": "string", "format": "uri"},
                                     "geovisio:thumbnail": {"type": "string", "format": "uri"},
+                                    "geovisio:rank_in_collection": {
+                                        "type": "integer",
+                                        "minimum": 1,
+                                        "title": "Rank of the picture in its collection.",
+                                    },
                                     "original_file:size": {"type": "integer", "minimum": 0, "title": "Size of the original file, in bytes"},
                                     "original_file:name": {"type": "string", "title": "Original file name"},
                                     "panoramax:horizontal_pixel_density": {
@@ -525,7 +559,7 @@ The CSV headers will be:
                     "override_capture_time": {
                         "type": "string",
                         "format": "date-time",
-                        "description": "datetime when the picture was taken. It will change the picture's metadata with this datetime. It should be an iso 3339 formated datetime (like '2017-07-21T17:32:28Z')",
+                        "description": "datetime when the picture was taken. It will change the picture's metadata with this datetime. It should be an iso 3339 formatted datetime (like '2017-07-21T17:32:28Z')",
                     },
                     "override_latitude": {
                         "type": "number",
@@ -578,6 +612,20 @@ Example values are:
 Note that this parameter is not taken in account for 360° pictures, as by definition a nearby place would be theorically always visible in it.
 """,
                             },
+                            "sortby": {
+                                "description": """Define the sort order of the results of a search. 
+Sort order is defined based on preceding '+' (asc) or '-' (desc).
+
+By default we sort to get the last updated pictures first.
+
+Available properties are:
+* `ts`: capture datetime of the picture
+* `updated`: sort by updated datetime of the picture
+* `id`: us the picture ID for sort
+""",
+                                "default": "-updated",
+                                "type": "string",
+                            },
                         },
                     },
                 ],
@@ -742,6 +790,10 @@ Available properties are:
                         "properties": {
                             "user_profile": {"type": "object", "properties": {"url": {"type": "string"}}},
                             "enabled": {"type": "boolean"},
+                            "registration_is_open": {
+                                "type": "boolean",
+                                "description": "If true, users can create their own account on the instance. Only used for reference in the federation for the moment",
+                            },
                             "enforce_tos_acceptance": {"type": "boolean"},
                         },
                         "required": ["enabled"],
@@ -759,6 +811,32 @@ Available properties are:
                         "description": "The GeoVisio API version number",
                         "example": "2.6.0-12-ab12cd34",
                     },
+                    "defaults": {
+                        "type": "object",
+                        "properties": {
+                            "collaborative_metadata": {
+                                "type": "integer",
+                                "description": "If `true`, the pictures's metadata will be, by default, editable by all users.",
+                            },
+                            "split_distance": {
+                                "type": "integer",
+                                "description": "Maximum distance between two pictures to be considered in the same sequence (in meters). If both split_distance and split_time are None, no split will occur by default.",
+                            },
+                            "split_time": {
+                                "type": "integer",
+                                "description": "Maximum time interval between two pictures to be considered in the same sequence. If both split_distance and split_time are None, no split will occur by default.",
+                            },
+                            "duplicate_distance": {
+                                "type": "integer",
+                                "description": "Maximum distance between two pictures to be considered as duplicates (in meters). If both duplicate_distance andduplicate_rotation are None, no deduplication will occur by default.",
+                            },
+                            "duplicate_rotation": {
+                                "type": "integer",
+                                "description": "Maximum angle of rotation for two too-close-pictures to be considered as duplicates (in degrees).",
+                            },
+                        },
+                        "required": ["collaborative_metadata", "duplicate_distance", "duplicate_rotation", "split_distance", "split_time"],
+                    },
                 },
                 "required": ["auth"],
             },
@@ -821,6 +899,15 @@ Available properties are:
                     "payload": {"type": "object", "description": "The error payload"},
                 },
             },
+            "GeoVisioAnnotation": annotations_utils.Annotation.model_json_schema(
+                ref_template="#/components/schemas/GeoVisioAnnotation/$defs/{model}", mode="serialization"
+            ),
+            "GeoVisioPostAnnotation": annotations.AnnotationPostParameter.model_json_schema(
+                ref_template="#/components/schemas/GeoVisioPostAnnotation/$defs/{model}", mode="serialization"
+            ),
+            "GeoVisioPatchAnnotation": annotations.AnnotationPatchParameter.model_json_schema(
+                ref_template="#/components/schemas/GeoVisioPatchAnnotation/$defs/{model}", mode="serialization"
+            ),
         },
         "parameters": {
             "STAC_bbox": {"$ref": f"https://api.stacspec.org/v{utils.STAC_VERSION}/item-search/openapi.yaml#/components/parameters/bbox"},
@@ -848,7 +935,7 @@ Available properties are:
                 "description": """
 A CQL2 filter expression for filtering sequences.
 
-Allowed properties are: 
+Allowed properties are:
  * "created": upload date
  * "updated": last edit date
  * "status": status of the sequence. Can either be "ready" (for collections ready to be served) or "deleted"  for deleted collection. By default, only the "ready" collections will be shown.
@@ -872,7 +959,7 @@ Examples:
                 "description": """
 A CQL2 filter expression for filtering tiles.
 
-Allowed properties are: 
+Allowed properties are:
  * "status": status of the sequence. Can either be "ready" (for collections ready to be served) or "hidden" for hidden collections. By default, only the "ready" collections will be shown.
 
 Usage doc can be found here: https://docs.geoserver.org/2.23.x/en/user/tutorials/cql/cql_tutorial.html
@@ -916,13 +1003,58 @@ Note that this parameter is not taken in account for 360° pictures, as by defin
                 "required": False,
                 "schema": {"type": "integer", "minimum": 2, "maximum": 180, "default": 30},
             },
+            "GeoVisioSearchSortedBy": {
+                "name": "sortby",
+                "in": "query",
+                "description": """Define the sort order of the results of a search. 
+Sort order is defined based on preceding '+' (asc) or '-' (desc).
+
+By default we sort to get the last updated pictures firstn (-updated).
+
+Available properties are:
+* `ts`: capture datetime of the picture
+* `updated`: sort by updated datetime of the picture
+* `id`: us the picture ID for sort
+""",
+                "required": False,
+                "schema": {
+                    "type": "string",
+                },
+            },
+            "searchCQL2_filter": {
+                "name": "filter",
+                "in": "query",
+                "description": """
+A CQL2 filter expression for filtering search results.
+
+Only works for semantic search for the moment.
+
+The attributes must start with "semantics." and formated like "semantics.some_key"='some_value'.
+
+Note: it's important for the attribute to be quoted (`"`) and the value to around simple quotes (`'`) to avoid issues with CQL2 parsing.
+
+For the moment only equality (`=`) and list (`IN`) filters are supported. We do not support searching for multiple different tags at once with an `AND` operator (for example, `"semantics.traffic_sign"='yes' AND "semantics.colour"='red'` __will not work__). We suggest to filter data on your side, after retrieving by the main attribute depending on your interest.
+
+To search for any values of a semantic tag, use `semantics.some_key IS NOT NULL` (case matter here).
+
+Examples:
+
+* "semantics.osm|traffic_sign"='yes'
+* "semantics.osm|traffic_sign" IS NOT NULL'
+* "semantics.osm|amenity" IN ('bench', 'whatever') OR "semantics.osm|traffic_sign"='yes'
+""",
+                "required": False,
+                "schema": {
+                    "type": "string",
+                },
+            },
             "GeoVisioReports_filter": {
                 "name": "filter",
                 "in": "query",
                 "description": """
 A CQL2 filter expression for filtering reports.
 
-Allowed properties are: 
+Allowed properties are:
  * status: 'open', 'open_autofix', 'waiting', 'closed_solved', 'closed_ignored'
  * reporter: 'me', user account ID or unset
  * owner: 'me', user account ID or unset
@@ -947,7 +1079,7 @@ By default, we only show open or waiting reports, sorted by descending creation
                 "description": """
 A CQL2 filter expression for filtering reports.
 
-Allowed properties are: 
+Allowed properties are:
  * status: 'open', 'open_autofix', 'waiting', 'closed_solved', 'closed_ignored'
  * reporter: 'me' or unset
  * owner: 'me' or unset
@@ -972,7 +1104,7 @@ By default, we only show open or waiting reports concerning you, sorted by desce
                 "description": """
 A CQL2 filter expression for filtering upload sets.
 
-Allowed properties are: 
+Allowed properties are:
  * completed: TRUE or FALSE
  * dispatched: TRUE or FALSE
 
@@ -1042,7 +1174,7 @@ def getApiInfo():
     """Return API metadata parsed from pyproject.toml"""
     apiMeta = metadata.metadata("geovisio")
 
-    # url is formated like 'Home, <url>
+    # url is formatted like 'Home, <url>
     url = apiMeta["Project-URL"].split(",")[1].rstrip()
     # there can be several authors, but we only display the first one in docs
     author = apiMeta["Author-email"].split(",")[0]