[feature] Add API endpoint for indoor map coordinates #828

docs/user/rest-api.rst

@@ -956,6 +956,29 @@ Delete Floor Plan
 
     DELETE /api/v1/controller/floorplan/{pk}/
 
+List Indoor Coordinates of a Location
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    This endpoint returns device coordinates from the first floor above
+    ground (lowest non-negative floors) by default. If a location only has
+    negative floors (e.g. underground parking lot), then it will return
+    the closest floor to the ground (greatest negative floor).
+
+.. code-block:: text
+
+    GET /api/v1/controller/location/{id}/indoor-coordinates/
+
+**Available filters**
+
+You can filter using ``floor`` to get list of devices and their indoor
+coodinates for that floor.
+
+.. code-block:: text
+
+    GET /api/v1/controller/location/{id}/indoor-coordinates/?floor={floor}
+
 List Templates
 ~~~~~~~~~~~~~~
 

openwisp_controller/geo/api/serializers.py

@@ -348,3 +348,48 @@ def update(self, instance, validated_data):
         )
         validated_data = self._validate(validated_data)
         return super().update(instance, validated_data)
+
+
+class IndoorCoordinatesSerializer(serializers.ModelSerializer):
+    admin_edit_url = SerializerMethodField("get_admin_edit_url")
+    device_id = serializers.UUIDField(source="content_object.id", read_only=True)
+    floorplan_id = serializers.UUIDField(source="floorplan.id", read_only=True)
+    device_name = serializers.CharField(source="content_object.name")
+    mac_address = serializers.CharField(source="content_object.mac_address")
+    floor_name = serializers.SerializerMethodField()
+    floor = serializers.IntegerField(source="floorplan.floor")
+    image = serializers.ImageField(source="floorplan.image", read_only=True)
+    coordinates = serializers.SerializerMethodField()
+
+    class Meta:
+        model = DeviceLocation
+        fields = [
+            "id",
+            "admin_edit_url",
+            "device_id",
+            "floorplan_id",
+            "device_name",
+            "mac_address",
+            "floor_name",
+            "floor",
+            "image",
+            "coordinates",
+        ]
+
+    def get_admin_edit_url(self, obj):
+        return self.context["request"].build_absolute_uri(
+            reverse(
+                f"admin:{obj.content_object._meta.app_label}_device_change",
+                args=(obj.content_object.id,),
+            )
+        )
+
+    def get_floor_name(self, obj):
+        return str(obj.floorplan)
+
+    def get_coordinates(self, obj):
+        """
+        NetJsonGraph expects indoor coordinates in {'lat': y, 'lng': x}.
+        """
+        y, x = obj.indoor.split(",", 1)
+        return {"lat": float(y), "lng": float(x)}

openwisp_controller/geo/api/views.py

@@ -1,6 +1,7 @@
 from django.core.exceptions import ObjectDoesNotExist, ValidationError
 from django.db.models import Count
 from django.http import Http404
+from django.utils.translation import gettext_lazy as _
 from django_filters import rest_framework as filters
 from rest_framework import generics, pagination, status
 from rest_framework.exceptions import NotFound, PermissionDenied
@@ -14,13 +15,18 @@
 from openwisp_users.api.filters import OrganizationManagedFilter
 from openwisp_users.api.mixins import FilterByOrganizationManaged, FilterByParentManaged
 
-from ...mixins import ProtectedAPIMixin, RelatedDeviceProtectedAPIMixin
+from ...mixins import (
+    BaseProtectedAPIMixin,
+    ProtectedAPIMixin,
+    RelatedDeviceProtectedAPIMixin,
+)
 from .filters import DeviceListFilter
 from .serializers import (
     DeviceCoordinatesSerializer,
     DeviceLocationSerializer,
     FloorPlanSerializer,
     GeoJsonLocationSerializer,
+    IndoorCoordinatesSerializer,
     LocationDeviceSerializer,
     LocationSerializer,
 )
@@ -51,6 +57,37 @@ class Meta(OrganizationManagedFilter.Meta):
         model = FloorPlan
 
 
+class IndoorCoordinatesFilter(filters.FilterSet):
+    floor = filters.NumberFilter(label=_("Floor"), method="filter_by_floor")
+
+    @property
+    def qs(self):
+        qs = super().qs
+        if "floor" not in self.data:
+            qs = self.filter_by_floor(qs, "floor", None)
+        return qs
+
+    def filter_by_floor(self, queryset, name, value):
+        """
+        If no floor parameter is provided:
+        - Return data for the first available non-negative floor.
+        - If no non-negative floor exists, return data for the maximum negative floor.
+        """
+        if value is not None:
+            return queryset.filter(floorplan__floor=value)
+        # No floor parameter provided
+        floors = list(queryset.values_list("floorplan__floor", flat=True).distinct())
+        if not floors:
+            return queryset.none()
+        non_negative_floors = [f for f in floors if f >= 0]
+        default_floor = min(non_negative_floors) if non_negative_floors else max(floors)
+        return queryset.filter(floorplan__floor=default_floor)
+
+    class Meta(OrganizationManagedFilter.Meta):
+        model = DeviceLocation
+        fields = ["floor"]
+
+
 class ListViewPagination(pagination.PageNumberPagination):
     page_size = 10
     page_size_query_param = "page_size"
@@ -186,6 +223,47 @@ class GeoJsonLocationList(
     filterset_class = LocationOrganizationFilter
 
 
+class IndoorCoodinatesViewPagination(ListViewPagination):
+    page_size = 50
+
+
+class IndoorCoordinatesList(
+    FilterByParentManaged, BaseProtectedAPIMixin, generics.ListAPIView
+):
+    serializer_class = IndoorCoordinatesSerializer
+    filter_backends = [filters.DjangoFilterBackend]
+    filterset_class = IndoorCoordinatesFilter
+    pagination_class = IndoorCoodinatesViewPagination
+    queryset = (
+        DeviceLocation.objects.filter(
+            location__type="indoor",
+            floorplan__isnull=False,
+        )
+        .select_related(
+            "content_object", "location", "floorplan", "location__organization"
+        )
+        .order_by("floorplan__floor")
+    )
+
+    def get_parent_queryset(self):
+        qs = Location.objects.filter(pk=self.kwargs["pk"])
+        return qs
+
+    def get_queryset(self):
+        return super().get_queryset().filter(location_id=self.kwargs["pk"])
+
+    def get_available_floors(self, qs):
+        floors = list(qs.values_list("floorplan__floor", flat=True).distinct())
+        return floors
+
+    def list(self, request, *args, **kwargs):
+        floors = self.get_available_floors(self.get_queryset())
+        response = super().list(request, *args, **kwargs)
+        if response.status_code == 200:
+            response.data["floors"] = floors
+        return response
+
+
 class LocationDeviceList(
     FilterByParentManaged, ProtectedAPIMixin, generics.ListAPIView
 ):
@@ -202,6 +280,17 @@ def get_queryset(self):
         qs = Device.objects.filter(devicelocation__location_id=self.kwargs["pk"])
         return qs
 
+    def get_has_floorplan(self, qs):
+        qs = qs.filter(devicelocation__floorplan__isnull=False).exists()
+        return qs
+
+    def list(self, request, *args, **kwargs):
+        has_floorplan = self.get_has_floorplan(self.get_queryset())
+        response = super().list(self, request, *args, **kwargs)
+        if response.status_code == 200:
+            response.data["has_floorplan"] = has_floorplan
+        return response
+
 
 class FloorPlanListCreateView(ProtectedAPIMixin, generics.ListCreateAPIView):
     serializer_class = FloorPlanSerializer
@@ -244,5 +333,6 @@ class LocationDetailView(
 location_device_list = LocationDeviceList.as_view()
 list_floorplan = FloorPlanListCreateView.as_view()
 detail_floorplan = FloorPlanDetailView.as_view()
+indoor_coordinates_list = IndoorCoordinatesList.as_view()
 list_location = LocationListCreateView.as_view()
 detail_location = LocationDetailView.as_view()