👽 feat: added API endpoint for image_search

Signed-off-by: saif <[email protected]>

Author: Rubix982

src/mapillary/config/api/entities.py

@@ -15,12 +15,21 @@
 """
 
 # Local imports
+import datetime
+import logging
+import typing
+
+# # Utils
+from mapillary.utils.time import is_iso8601_datetime_format
 
-# # Exception Handling
+# # Models
+# # # Exception Handling
 from mapillary.models.exceptions import InvalidFieldError, InvalidNumberOfArguments
+from mapillary.models.config import Config
+from mapillary.models.logger import Logger
+
+logger: logging.Logger = Logger.setup_logger(name="mapillary.config.api.entities")
 
-# # Imports
-import typing
 
 class Entities:
     """
@@ -90,7 +99,9 @@ def get_image(image_id: str, fields: list) -> str:
         return f"https://graph.mapillary.com/{image_id}/?fields={','.join(fields)}"
 
     @staticmethod
-    def get_images(image_ids: typing.List[str], fields: list) -> str:
+    def get_images(
+        image_ids: typing.Union[typing.List[str], typing.List[int]], fields: list
+    ) -> str:
         """
         Represents the metadata of the image on the Mapillary platform with
         the following properties.
@@ -101,7 +112,8 @@ def get_images(image_ids: typing.List[str], fields: list) -> str:
 
         Parameters::
 
-            A list of entity IDs separated by comma. The provided IDs must be in the same type (e.g. all image IDs, or all detection IDs)
+            A list of entity IDs separated by comma. The provided IDs must be in the same type
+            (e.g. all image IDs, or all detection IDs)
 
         Fields::
 
@@ -130,7 +142,7 @@ def get_images(image_ids: typing.List[str], fields: list) -> str:
             22. width - int, width of the original image uploaded
 
         Raises::
-            
+
             InvalidNumberOfArguments - if the number of ids passed is 0 or greater than 50
         """
 
@@ -140,7 +152,11 @@ def get_images(image_ids: typing.List[str], fields: list) -> str:
         # in the future
 
         if len(image_ids) == 0 or len(image_ids) > 50:
-            raise InvalidNumberOfArguments(number_of_params_passed=len(image_ids), actual_allowed_params=50, param="image_ids")
+            raise InvalidNumberOfArguments(
+                number_of_params_passed=len(image_ids),
+                actual_allowed_params=50,
+                param="image_ids",
+            )
 
         fields = Entities.__field_validity(
             given_fields=fields,
@@ -150,6 +166,193 @@ def get_images(image_ids: typing.List[str], fields: list) -> str:
 
         return f"https://graph.mapillary.com/ids={','.join(image_ids)}?fields={','.join(fields)}"
 
+    @staticmethod
+    def search_for_images(  # noqa: C901, 'search_for_images is too complex'
+        bbox: typing.List[float],
+        start_captured_at: typing.Optional[datetime.datetime] = None,
+        end_captured_at: typing.Optional[datetime.datetime] = None,
+        limit: typing.Optional[int] = None,
+        organization_id: typing.Union[
+            typing.Optional[int], typing.Optional[str]
+        ] = None,
+        sequence_id: typing.Optional[typing.List[int]] = None,
+        fields: typing.Optional[list] = [],
+    ) -> str:
+        """
+        Represents the metadata of the image on the Mapillary platform with
+        the following properties.
+
+        Output Format::
+
+            >>> 'https://graph.mapillary.com/search?bbox=LONG1,LAT1,LONG2,LAT2' # endpoint
+            >>> 'https://graph.mapillary.com/search?bbox=LONG1,LAT1,LONG2,LAT2&start_time='
+            'START_TIME' # endpoint
+            >>> 'https://graph.mapillary.com/search?bbox=LONG1,LAT1,LONG2,LAT2&start_time='
+            'START_TIME&end_time=END_TIME' # endpoint
+            >>> 'https://graph.mapillary.com/search?bbox=LONG1,LAT1,LONG2,LAT2&start_time='
+            'START_TIME&end_time=END_TIME&limit=LIMIT' # endpoint
+            >>> 'https://graph.mapillary.com/search/images?bbox=LONG1,LAT1,LONG2,LAT2&start_time'
+            '=START_TIME&end_time=END_TIME&limit=LIMIT&organization_id=ORGANIZATION_ID&'
+            'sequence_id=SEQUENCE_ID1' # endpoint
+            >>> 'https://graph.mapillary.com/search/images?bbox=LONG1,LAT1,LONG2,LAT2&start_time='
+            'START_TIME&end_time=END_TIME&limit=LIMIT&organization_id=ORGANIZATION_ID&sequence_id'
+            '=SEQUENCE_ID1,SEQUENCE_ID2,SEQUENCE_ID3' # endpoint
+
+        Usage::
+
+            >>> from mapillary.config.api.entities import Entities
+            >>> bbox = [-180, -90, 180, 90]
+            >>> start_captured_at = datetime.datetime(2020, 1, 1, 0, 0, 0)
+            >>> end_captured_at = datetime.datetime(2022, 1, 1, 0, 0, 0)
+            >>> organization_id = 123456789
+            >>> sequence_ids = [123456789, 987654321]
+            >>> Entities.search_for_images(bbox=bbox) # endpoint
+            'https://graph.mapillary.com/search?bbox=-180,-90,180,90' # endpoint
+            >>> Entities.search_for_images(bbox=bbox, start_captured_at=start_captured_at)
+            'https://graph.mapillary.com/search?bbox=-180,-90,180,90&start_time=' # endpoint
+            >>> Entities.search_for_images(bbox=bbox,
+            ... start_captured_at=start_captured_at, end_captured_at=end_captured_at)
+            'https://graph.mapillary.com/search?bbox=-180,-90,180,90&start_time=&'
+            'end_time=' # endpoint
+            >>> Entities.search_for_images(bbox=bbox,
+            ... start_captured_at=start_captured_at, end_captured_at=end_captured_at,
+            ... limit=100)
+            'https://graph.mapillary.com/search?bbox=-180,-90,180,90&start_time=&end_time=&limit'
+            '=100' # endpoint
+            >>> Entities.search_for_images(bbox=bbox,
+            ... start_captured_at=start_captured_at, end_captured_at=end_captured_at,
+            ... limit=100, organization_id=organization_id, sequence_id=sequence_ids)
+            'https://graph.mapillary.com/search/images?bbox=-180,-90,180,90&start_time=&end_time'
+            '=&limit=100&organization_id=1234567890&sequence_id=1234567890' # endpoint
+
+        :param bbox: float,float,float,float: filter images in the bounding box. Specify in this
+        order: left, bottom, right, top (or minLon, minLat, maxLon, maxLat).
+        :type bbox: typing.Union[typing.List[float], typing.Tuple[float, float, float, float],
+        list, tuple]
+
+        :param start_captured_at: filter images captured after. Specify in the ISO 8601 format.
+        For example: "2022-08-16T16:42:46Z".
+        :type start_time: typing.Union[typing.Optional[datetime.datetime], typing.Optional[str]]
+        :default start_captured_at: None
+
+        :param end_captured_at: filter images captured before. Same format as
+        "start_captured_at".
+        :type end_time: typing.Union[typing.Optional[datetime.datetime], typing.Optional[str]]
+        :default end_captured_at: None
+
+        :param limit: limit the number of images returned. Max and default is 2000. The 'default'
+        here means the default value of `limit` assumed on the server's end if the limit param
+        is not passed. In other words, if the `limit` parameter is set to `None`, the server will
+        assume the `limit` parameter to be 2000, which is the same as setting the `limit`
+        parameter to 2000 explicitly.
+        :type limit: typing.Optional[int]
+        :default limit: None
+
+        :param organization_id: filter images contributed to the specified organization Id.
+        :type organization_id: typing.Optional[int]
+        :default organization_id: None
+
+        :param sequence_id: filter images in the specified sequence Ids (separated by commas),
+        For example, "[1234567890,1234567891,1234567892]".
+        :type sequence_id: typing.Optional[typing.List[int], int]
+        :default sequence_id: None
+
+        :param fields: filter the fields returned. For example, "['atomic_scale', 'altitude',
+        'camera_parameters']". For more information, see
+        https://www.mapillary.com/developer/api-documentation/#image. To get list of all possible
+        fields, please use Entities.get_image_fields()
+        :type fields: typing.Optional[typing.List[str]]
+        :default fields: []
+
+        :return: endpoint for searching an image
+        :rtype: str
+        """
+
+        fields = Entities.__field_validity(
+            given_fields=fields,
+            actual_fields=Entities.get_image_fields(),
+            endpoint="https://graph.mapillary.com/images?bbox=,:parameters=,:fields=",
+        )
+
+        parameter_string: str = ""
+
+        parameters = {
+            "start_captured_at": start_captured_at,
+            "end_captured_at": end_captured_at,
+            "limit": limit,
+            "organization_id": organization_id,
+            "sequence_id": sequence_id,
+        }
+
+        # For each item in the given parameters ...
+        for key, value in parameters.items():
+
+            # ... if it is not None ...
+            if value is not None:
+
+                # ... if the key is about time ...
+                if key in ["start_captured_at", "end_captured_at"]:
+
+                    # ... if the datatype is a string ...
+                    if isinstance(value, str):
+
+                        # ... check if the string is a valid datetime in the ISO8601 format ...
+                        if not is_iso8601_datetime_format(value) and Config.use_strict:
+
+                            # ... if not, raise an error ...
+                            if Config.use_strict:
+
+                                # Raising ValueError if strict mode is enabled
+                                raise ValueError(
+                                    f"""{key} must be in the ISO 8601 format. For example:
+                                    '2022-08-16T16:42:46Z'."""
+                                )
+
+                            else:
+
+                                logger.warning(
+                                    f"{key} must be in the ISO 8601 format. For example:"
+                                    f"'2022-08-16T16:42:46Z'. Disregarding {key} parameter."
+                                    "Continuing without strict mode enabled."
+                                )
+
+                            # ... if not, just move on - no assumptions on the `date string` ...
+                            continue
+
+                    # ... if the value is a valid datetime object ...
+                    elif isinstance(value, datetime.datetime):
+
+                        # ... convert it to the ISO 8601 format required ...
+                        value = value.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+                # ... if the key is limit ...
+                if key == "limit":
+
+                    # Check if it is within limits
+                    if value > 2000:
+
+                        # Log warning if not, waring mode is enabled - logger object declared
+                        # globally is used
+                        logger.warning(f"{key} is greater than 2000. Setting to 2000.")
+
+                        # Set the value to 2000
+                        value = 2000
+
+                # ... if the key is sequence_id ...
+                if key == "sequence_id":
+                    # ... convert the list into string ...
+                    value = ",".join(map(str, value))
+
+                # ... add it to the parameter string
+                parameter_string += f"&{key}={value}"
+
+        # Return the endpoint
+        return (
+            f"https://graph.mapillary.com/images?bbox={','.join([str(val) for val in bbox])}"
+            f"{parameter_string if parameter_string != '' else ''}"
+            f"{'&fields=' + ','.join(fields) if fields != [] else ''}"
+        )
+
     @staticmethod
     def get_image_fields() -> list:
         """
@@ -403,6 +606,9 @@ def __field_validity(
         :rtype: list
         """
 
+        if len(given_fields) == 0:
+            return given_fields  # empty list: []
+
         # Converting the given_fields into lowercase
         given_fields = [field.lower() for field in given_fields]