feat: add geocoding functionality

chore: bump version number (v0.0.9 -> v0.0.10)

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pandora-cas"
-version = "0.0.9"
+version = "0.0.10"
 description = "Pandora Car Alarm System clientside API implementation"
 authors = ["Alexander Ryazanov <[email protected]>"]
 readme = "README.md"

src/pandora_cas/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.0.9"
+__version__ = "0.0.10"
 __author__ = "Alexander Ryazanov <[email protected]>"
 __all__ = ("account", "data", "device", "enums", "errors")

src/pandora_cas/account.py

@@ -738,6 +738,38 @@ async def async_request_updates(
 
         return device_new_attrs, events
 
+    async def async_geocode(
+        self,
+        latitude: float,
+        longitude: float,
+        language: str | None = None,
+        full: bool = False,
+    ) -> str | dict[str, str] | None:
+        """
+        Retrieve the geocoded location for the given latitude and longitude.
+        :param latitude: Latitude
+        :param longitude: Longitude
+        :param language: Language code
+        :param full: Whether to return the whole response
+        :return: (Whole response) OR (Short address) OR (None if empty)
+        """
+        if not (access_token := self.access_token):
+            raise MissingAccessTokenError("Account is not authenticated")
+        if language is None:
+            language = "ru"
+        async with self._session.get(
+            self.BASE_URL + "/api/geo",
+            params={
+                "lang": language,
+                "lat": latitude,
+                "lon": longitude,
+                "access_token": access_token,
+                # "_": 0,
+            },
+        ) as response:
+            response = await self._handle_dict_response(response)
+        return response if full else response.get("short") or None
+
     def _process_ws_initial_state(
         self, device: "PandoraOnlineDevice", data: Mapping[str, Any]
     ) -> tuple[CurrentState, dict[str, Any]]:

src/pandora_cas/device.py

@@ -194,6 +194,23 @@ def update_current_state(self, **state_args) -> tuple[CurrentState, dict[str, An
         self.state = new_state
         return new_state, state_args
 
+    async def async_geocode(
+        self, language: str | None = None, full: bool = False
+    ) -> str | dict[str, str] | None:
+        """
+        Retrieve the geocoded location for the given latitude and longitude.
+        :param language: Language code
+        :param full: Whether to return the whole response
+        :return: (Whole response) OR (Short address) OR (None if empty)
+        """
+        if not (state := self.state):
+            raise ValueError("State is not available")
+        if None in (state.latitude, state.longitude):
+            raise ValueError("Both latitude and longitude are required")
+        return await self.account.async_geocode(
+            state.latitude, state.longitude, language, full
+        )
+
     async def async_fetch_last_event(self) -> TrackingEvent | None:
         try:
             return next(iter(await self.async_fetch_events(0, None, 1)))