[OSDEV-1577] Add geo-bounding box support to the GET /v1/production-locations/ endpoint

doc/release/RELEASE-NOTES.md

@@ -19,36 +19,44 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 * *Describe schema changes here.*
 
 ### Code/API changes
-* *Describe code/API changes here.*
+* [OSDEV-1577](https://opensupplyhub.atlassian.net/browse/OSDEV-1577) - Added geo-bounding box query support to the GET `/api/v1/production-locations/` endpoint. To filter production locations whose geopoints fall within the bounding box, it is necessary to specify valid values for the parameters `geo_bounding_box[top]`, `geo_bounding_box[left]`, `geo_bounding_box[bottom]`, and `geo_bounding_box[right]`. 
+
+    The validation rules are as follows:
+    * All coordinates of the geo-boundary box (top, left, bottom, right) must be provided.
+    * All values must be integers.
+    * The top and bottom coordinates must be between -90 and 90.
+    * The left and right coordinates must be between -180 and 180.
+    * The top must be greater than the bottom.
+    * The right must be greater than the left.
 
 ### Architecture/Environment changes
 * [OSDEV-899](https://opensupplyhub.atlassian.net/browse/OSDEV-899) - With this task, we split the Django container into two components: FE (React) and BE (Django). Requests to the frontend (React) will be processed by the CDN (CloudFront), while requests to the API will be redirected to the Django container. This approach will allow for more efficient use of ECS cluster computing resources and improve frontend performance.
 
-  The following endpoints will be redirected to the Django container:
-  * tile/*
-  * api/*
-  * /api-auth/*
-  * /api-token-auth/*
-  * /api-feature-flags/*
-  * /web/environment.js
-  * /admin/*
-  * /health-check/*
-  * /rest-auth/*
-  * /user-login/*
-  * /user-logout/*
-  * /user-signup/*
-  * /user-profile/*
-  * /user-api-info/*
-  * /admin
-  * /static/admin/*
-  * /static/django_extensions/*
-  * /static/drf-yasg/*
-  * /static/gis/*
-  * /static/rest_framework/*
-  * /static/static/*
-  * /static/staticfiles.json
-
-  All other traffic will be redirected to the React application.
+    The following endpoints will be redirected to the Django container:
+    * tile/*
+    * api/*
+    * /api-auth/*
+    * /api-token-auth/*
+    * /api-feature-flags/*
+    * /web/environment.js
+    * /admin/*
+    * /health-check/*
+    * /rest-auth/*
+    * /user-login/*
+    * /user-logout/*
+    * /user-signup/*
+    * /user-profile/*
+    * /user-api-info/*
+    * /admin
+    * /static/admin/*
+    * /static/django_extensions/*
+    * /static/drf-yasg/*
+    * /static/gis/*
+    * /static/rest_framework/*
+    * /static/static/*
+    * /static/staticfiles.json
+
+    All other traffic will be redirected to the React application.
 
 ### Bugfix
 * *Describe bugfix here.*

src/django/api/constants.py

@@ -207,6 +207,13 @@ class FacilitiesListSettings:
     DEFAULT_PAGE_LIMIT = 100
 
 
+class CoordinateLimits:
+    LAT_MIN = -90
+    LAT_MAX = 90
+    LNG_MIN = -180
+    LNG_MAX = 180
+
+
 # API v1
 class APIV1CommonErrorMessages:
     COMMON_REQ_BODY_ERROR = 'The request body is invalid.'

src/django/api/serializers/v1/opensearch_common_validators/coordinates_validator.py

@@ -1,4 +1,5 @@
 from typing import List
+from api.constants import CoordinateLimits
 from api.serializers.v1.opensearch_validation_interface \
     import OpenSearchValidationInterface
 
@@ -18,14 +19,18 @@ def validate_opensearch_params(self, data) -> List[dict]:
             })
 
         if lat is not None:
-            if not (-90 <= lat <= 90):
+            if not (
+                CoordinateLimits.LAT_MIN <= lat <= CoordinateLimits.LAT_MAX
+            ):
                 errors.append({
                     "field": "coordinates",
                     "detail": "Latitude must be between -90 and 90 degrees."
                 })
 
         if lng is not None:
-            if not (-180 <= lng <= 180):
+            if not (
+                CoordinateLimits.LNG_MIN <= lng <= CoordinateLimits.LNG_MAX
+            ):
                 errors.append({
                     "field": "coordinates",
                     "detail":

src/django/api/serializers/v1/opensearch_common_validators/geo_bounding_box_validator.py

@@ -0,0 +1,67 @@
+from api.constants import CoordinateLimits
+from api.serializers.v1.opensearch_validation_interface import (
+    OpenSearchValidationInterface,
+)
+
+
+class GeoBoundingBoxValidator(OpenSearchValidationInterface):
+    def validate_opensearch_params(self, data):
+        errors = []
+
+        fields = ['top', 'left', 'bottom', 'right']
+        coords = {
+            field: data.get(f'geo_bounding_box_{field}') for field in fields
+        }
+
+        if any(value is not None for value in coords.values()) and not all(
+            value is not None for value in coords.values()
+        ):
+            errors.append(
+                {
+                    "field": "geo_bounding_box",
+                    "detail": "All coordinates (top, left, bottom, right) "
+                    "must be provided.",
+                }
+            )
+
+            return errors
+
+        if not any(value is not None for value in coords.values()):
+            return errors
+
+        range_limits = {
+            'top': (CoordinateLimits.LAT_MIN, CoordinateLimits.LAT_MAX),
+            'bottom': (CoordinateLimits.LAT_MIN, CoordinateLimits.LAT_MAX),
+            'left': (CoordinateLimits.LNG_MIN, CoordinateLimits.LNG_MAX),
+            'right': (CoordinateLimits.LNG_MIN, CoordinateLimits.LNG_MAX),
+        }
+
+        for field, (min_val, max_val) in range_limits.items():
+            value = coords[field]
+
+            if value < min_val or value > max_val:
+                errors.append(
+                    {
+                        "field": "geo_bounding_box",
+                        "detail": f"The {field} value must be between "
+                        f"{min_val} and {max_val}.",
+                    }
+                )
+
+        if coords['top'] <= coords['bottom']:
+            errors.append(
+                {
+                    "field": "geo_bounding_box",
+                    "detail": "The top must be greater than bottom.",
+                }
+            )
+
+        if coords['right'] <= coords['left']:
+            errors.append(
+                {
+                    "field": "geo_bounding_box",
+                    "detail": "The right must be greater than left.",
+                }
+            )
+
+        return errors

src/django/api/serializers/v1/production_locations_serializer.py

@@ -20,6 +20,8 @@
 from api.serializers.v1.opensearch_common_validators. \
     coordinates_validator import CoordinatesValidator
 from api.constants import APIV1CommonErrorMessages
+from api.serializers.v1.opensearch_common_validators.\
+    geo_bounding_box_validator import GeoBoundingBoxValidator
 
 
 class ProductionLocationsSerializer(Serializer):
@@ -56,6 +58,10 @@ class ProductionLocationsSerializer(Serializer):
         max_value=15,
         required=False,
     )
+    geo_bounding_box_top = FloatField(required=False)
+    geo_bounding_box_left = FloatField(required=False)
+    geo_bounding_box_bottom = FloatField(required=False)
+    geo_bounding_box_right = FloatField(required=False)
 
     def validate(self, data):
         validators = [
@@ -64,6 +70,7 @@ def validate(self, data):
             PercentOfFemaleWorkersValidator(),
             CoordinatesValidator(),
             CountryValidator(),
+            GeoBoundingBoxValidator(),
         ]
 
         error_list_builder = OpenSearchErrorListBuilder(validators)

src/django/api/tests/test_production_locations_query_builder.py

@@ -256,3 +256,27 @@ def test_add_aggregations_where_aggregation_is_not_geohex_grid(self):
             aggregation
         )
         self.assertNotIn('aggregations', self.builder.query_body)
+
+    def test_add_geo_bounding_box(self):
+        top = 40.7128
+        left = -74.0060
+        bottom = 35.7128
+        right = -78.0060
+        self.builder.add_geo_bounding_box(top, left, bottom, right)
+        expected = {
+            'geo_bounding_box': {
+                'coordinates': {
+                    'top': top,
+                    'left': left,
+                    'bottom': bottom,
+                    'right': right,
+                }
+            }
+        }
+        self.assertIn(
+            'filter', self.builder.query_body['query']['bool']
+        )
+        self.assertEqual(
+            expected,
+            self.builder.query_body['query']['bool']['filter']
+        )

src/django/api/tests/test_v1_utils.py

@@ -193,3 +193,113 @@ def test_handle_opensearch_exception(self):
         self.assertIsInstance(response, Response)
         self.assertEqual(response.status_code, 500)
         self.assertEqual(response.data['detail'], "OpenSearch error")
+
+    def test_serialize_geo_bounding_box(self):
+        query_dict = QueryDict('', mutable=True)
+        query_dict.update(
+            {
+                'geo_bounding_box[top]': '90',
+                'geo_bounding_box[left]': '-180',
+                'geo_bounding_box[bottom]': '-90',
+                'geo_bounding_box[right]': '180',
+            }
+        )
+        serialized_params, error_response = serialize_params(
+            ProductionLocationsSerializer, query_dict
+        )
+        self.assertIsNone(error_response)
+        self.assertEqual(serialized_params['geo_bounding_box_top'], 90)
+        self.assertEqual(serialized_params['geo_bounding_box_left'], -180)
+        self.assertEqual(serialized_params['geo_bounding_box_bottom'], -90)
+        self.assertEqual(serialized_params['geo_bounding_box_right'], 180)
+
+    def test_serialize_geo_bounding_box_missing_values(self):
+        query_dict = QueryDict('', mutable=True)
+        query_dict.update(
+            {
+                'geo_bounding_box[top]': '90',
+                'geo_bounding_box[left]': '-180',
+                'geo_bounding_box[bottom]': '-90',
+            }
+        )
+        _, error_response = serialize_params(
+            ProductionLocationsSerializer, query_dict
+        )
+        self.assertIsNotNone(error_response)
+        self.assertEqual(
+            error_response['detail'], "The request query is invalid."
+        )
+        self.assertIn(
+            {
+                'field': 'geo_bounding_box',
+                'detail': 'All coordinates (top, left, bottom, right) '
+                'must be provided.',
+            },
+            error_response['errors'],
+        )
+
+    def test_serialize_geo_bounding_box_invalid_range(self):
+        query_dict = QueryDict('', mutable=True)
+        query_dict.update(
+            {
+                'geo_bounding_box[top]': '91',
+                'geo_bounding_box[left]': '-180',
+                'geo_bounding_box[bottom]': '-90',
+                'geo_bounding_box[right]': '181',
+            }
+        )
+        _, error_response = serialize_params(
+            ProductionLocationsSerializer, query_dict
+        )
+
+        self.assertIsNotNone(error_response)
+        self.assertEqual(
+            error_response['detail'], "The request query is invalid."
+        )
+        self.assertIn(
+            {
+                'field': 'geo_bounding_box',
+                'detail': 'The top value must be between -90 and 90.',
+            },
+            error_response['errors'],
+        )
+        self.assertIn(
+            {
+                'field': 'geo_bounding_box',
+                'detail': 'The right value must be between -180 and 180.',
+            },
+            error_response['errors'],
+        )
+
+    def test_serialize_geo_bounding_box_invalid_order(self):
+        query_dict = QueryDict('', mutable=True)
+        query_dict.update(
+            {
+                'geo_bounding_box[top]': '-90',
+                'geo_bounding_box[left]': '180',
+                'geo_bounding_box[bottom]': '90',
+                'geo_bounding_box[right]': '-180',
+            }
+        )
+        _, error_response = serialize_params(
+            ProductionLocationsSerializer, query_dict
+        )
+
+        self.assertIsNotNone(error_response)
+        self.assertEqual(
+            error_response['detail'], "The request query is invalid."
+        )
+        self.assertIn(
+            {
+                'field': 'geo_bounding_box',
+                'detail': 'The right must be greater than left.',
+            },
+            error_response['errors'],
+        )
+        self.assertIn(
+            {
+                'field': 'geo_bounding_box',
+                'detail': 'The top must be greater than bottom.',
+            },
+            error_response['errors'],
+        )

src/django/api/views/v1/opensearch_query_builder/opensearch_query_director.py

@@ -41,6 +41,7 @@ def build_query(self, query_params):
         self.__process_size(query_params)
         self.__process_multi_match(query_params)
         self.__process_aggregation(query_params)
+        self.__process_filter(query_params)
 
         return self.__builder.get_final_query_body()
 
@@ -131,3 +132,24 @@ def __process_aggregation(self, query_params):
 
         if aggregation and hasattr(self.__builder, 'add_aggregations'):
             self.__builder.add_aggregations(aggregation, geohex_grid_precision)
+
+    def __process_filter(self, query_params):
+        top = query_params.get(
+            V1_PARAMETERS_LIST.GEO_BOUNDING_BOX + '[top]'
+        )
+        left = query_params.get(
+            V1_PARAMETERS_LIST.GEO_BOUNDING_BOX + '[left]'
+        )
+        bottom = query_params.get(
+            V1_PARAMETERS_LIST.GEO_BOUNDING_BOX + '[bottom]'
+        )
+        right = query_params.get(
+            V1_PARAMETERS_LIST.GEO_BOUNDING_BOX + '[right]'
+        )
+
+        if top and left and bottom and right and hasattr(
+            self.__builder, 'add_geo_bounding_box'
+        ):
+            self.__builder.add_geo_bounding_box(
+                float(top), float(left), float(bottom), float(right)
+            )

src/django/api/views/v1/opensearch_query_builder/production_locations_query_builder.py

@@ -129,3 +129,15 @@ def add_aggregations(self, aggregation, geohex_grid_precision=None):
             }
 
         return self.query_body
+
+    def add_geo_bounding_box(self, top, left, bottom, right):
+        self.query_body['query']['bool']['filter'] = {
+            'geo_bounding_box': {
+                'coordinates': {
+                    'top': top,
+                    'left': left,
+                    'bottom': bottom,
+                    'right': right,
+                }
+            }
+        }