Add bounding box to states call

Author: joostlek

src/python_opensky/const.py

@@ -35,3 +35,9 @@ class AircraftCategory(int, Enum):
     POINT_OBSTACLE = 18
     CLUSTER_OBSTACLE = 19
     LINE_OBSTACLE = 20
+
+
+MIN_LATITUDE = "lamin"
+MAX_LATITUDE = "lamax"
+MIN_LONGITUDE = "lomin"
+MAX_LONGITUDE = "lomax"

src/python_opensky/exceptions.py

@@ -7,3 +7,7 @@ class OpenSkyError(Exception):
 
 class OpenSkyConnectionError(OpenSkyError):
     """OpenSky connection exception."""
+
+
+class OpenSkyCoordinateError(OpenSkyError):
+    """OpenSky coordinate exception."""

src/python_opensky/models.py

@@ -1,9 +1,12 @@
 """Asynchronous Python client for the OpenSky API."""
 from __future__ import annotations
 
+from dataclasses import dataclass
+
 from pydantic import BaseModel, Field
 
 from .const import AircraftCategory, PositionSource
+from .exceptions import OpenSkyCoordinateError
 
 
 class StatesResponse(BaseModel):
@@ -60,15 +63,34 @@ class StateVector(BaseModel):
     category: AircraftCategory = Field(...)
 
 
-class BoundingBox(BaseModel):
+@dataclass
+class BoundingBox:
     """Bounding box for retrieving state vectors."""
 
-    min_latitude: float = Field(...)
-    max_latitude: float = Field(...)
-    min_longitude: float = Field(...)
-    max_longitude: float = Field(...)
+    min_latitude: float
+    max_latitude: float
+    min_longitude: float
+    max_longitude: float
+
+    def validate(self) -> None:
+        """Validate if the latitude and longitude are correct."""
+        self._check_latitude(self.min_latitude)
+        self._check_latitude(self.max_latitude)
+        self._check_longitude(self.min_longitude)
+        self._check_longitude(self.max_longitude)
+
+    @staticmethod
+    def _check_latitude(degrees: float) -> None:
+        if degrees < -90 or degrees > 90:
+            msg = f"Invalid latitude {degrees}! Must be in [-90, 90]."
+            raise OpenSkyCoordinateError(msg)
+
+    @staticmethod
+    def _check_longitude(degrees: float) -> None:
+        if degrees < -180 or degrees > 180:
+            msg = f"Invalid longitude {degrees}! Must be in [-180, 180]."
+            raise OpenSkyCoordinateError(msg)
 
 
 StatesResponse.update_forward_refs()
 StateVector.update_forward_refs()
-BoundingBox.update_forward_refs()

src/python_opensky/opensky.py

@@ -12,8 +12,9 @@
 from aiohttp.hdrs import METH_GET
 from yarl import URL
 
+from .const import MAX_LATITUDE, MAX_LONGITUDE, MIN_LATITUDE, MIN_LONGITUDE
 from .exceptions import OpenSkyConnectionError, OpenSkyError
-from .models import StatesResponse
+from .models import BoundingBox, StatesResponse
 
 
 @dataclass
@@ -100,13 +101,20 @@ async def _request(
 
         return cast(dict[str, Any], await response.json())
 
-    async def states(self) -> StatesResponse:
+    async def states(self, bounding_box: BoundingBox | None = None) -> StatesResponse:
         """Retrieve state vectors for a given time."""
         params = {
             "time": 0,
             "extended": "true",
         }
 
+        if bounding_box:
+            bounding_box.validate()
+            params[MIN_LATITUDE] = bounding_box.min_latitude
+            params[MAX_LATITUDE] = bounding_box.max_latitude
+            params[MIN_LONGITUDE] = bounding_box.min_longitude
+            params[MAX_LONGITUDE] = bounding_box.max_longitude
+
         data = await self._request("states/all", data=params)
 
         keys = [

tests/test_models.py

@@ -0,0 +1,32 @@
+"""Tests for the OpenSky Library."""
+import pytest
+
+from python_opensky import BoundingBox
+from python_opensky.exceptions import OpenSkyCoordinateError
+
+
+def test_degrees() -> None:
+    """Test if validation passes."""
+    box: BoundingBox = BoundingBox(
+        min_latitude=0,
+        max_latitude=0,
+        min_longitude=0,
+        max_longitude=0,
+    )
+    box.validate()
+    box = BoundingBox(
+        min_latitude=-91,
+        max_latitude=0,
+        min_longitude=0,
+        max_longitude=0,
+    )
+    with pytest.raises(OpenSkyCoordinateError):
+        box.validate()
+    box = BoundingBox(
+        min_latitude=0,
+        max_latitude=0,
+        min_longitude=-181,
+        max_longitude=0,
+    )
+    with pytest.raises(OpenSkyCoordinateError):
+        box.validate()

tests/test_states.py

@@ -8,6 +8,7 @@
 
 from python_opensky import (
     AircraftCategory,
+    BoundingBox,
     OpenSky,
     OpenSkyConnectionError,
     OpenSkyError,
@@ -61,6 +62,33 @@ async def test_states(
         await opensky.close()
 
 
+async def test_states_with_bounding_box(
+    aresponses: ResponsesMockServer,
+) -> None:
+    """Test retrieving states."""
+    aresponses.add(
+        OPENSKY_URL,
+        "/api/states/all?time=0&extended=true&lamin=0&lamax=0&lomin=0&lomax=0",
+        "GET",
+        aresponses.Response(
+            status=200,
+            headers={"Content-Type": "application/json"},
+            text=load_fixture("states.json"),
+        ),
+        match_querystring=True,
+    )
+    async with aiohttp.ClientSession() as session:
+        opensky = OpenSky(session=session)
+        bounding_box = BoundingBox(
+            min_latitude=0,
+            max_latitude=0,
+            min_longitude=0,
+            max_longitude=0,
+        )
+        await opensky.states(bounding_box=bounding_box)
+        await opensky.close()
+
+
 async def test_new_session(
     aresponses: ResponsesMockServer,
 ) -> None: