visicom-api-client 0.1.0__py3-none-any.whl

visicom_api/__init__.py

@@ -0,0 +1,59 @@
+"""Unofficial Python client for the Visicom Data API."""
+
+from .async_client import AsyncVisicomClient
+from .client import VisicomClient
+from .exceptions import (
+    VisicomAPIError,
+    VisicomAuthError,
+    VisicomError,
+    VisicomRateLimitError,
+)
+from .models import (
+    AdmCountryProperties,
+    AdmDistrictProperties,
+    AdmLevel1Properties,
+    AdmLevel2Properties,
+    AdmLevel3Properties,
+    AdmSettlementProperties,
+    AdrAddressProperties,
+    AdrStreetProperties,
+    BufferResponse,
+    DistanceMatrixResponse,
+    DistanceResult,
+    FeatureCollection,
+    GeocodeResult,
+    GeoFeature,
+    LocationResponse,
+    PoiProperties,
+    SnapToRoadResult,
+    TspResponse,
+)
+
+__all__ = [
+    "VisicomClient",
+    "AsyncVisicomClient",
+    "VisicomError",
+    "VisicomAPIError",
+    "VisicomAuthError",
+    "VisicomRateLimitError",
+    "GeoFeature",
+    "FeatureCollection",
+    "GeocodeResult",
+    "AdmCountryProperties",
+    "AdmDistrictProperties",
+    "AdmLevel1Properties",
+    "AdmLevel2Properties",
+    "AdmLevel3Properties",
+    "AdmSettlementProperties",
+    "AdrAddressProperties",
+    "AdrStreetProperties",
+    "PoiProperties",
+    "DistanceResult",
+    "DistanceMatrixResponse",
+    "TspResponse",
+    "SnapToRoadResult",
+    "BufferResponse",
+    "LocationResponse",
+]
+
+__version__ = "0.1.0"

visicom_api/_base.py

@@ -0,0 +1,56 @@
+"""Shared helpers for query-parameter formatting.
+
+Not part of the public API; import from `visicom_api` instead.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Union
+
+BASE_URL = "https://api.visicom.ua/data-api/5.0"
+
+# A point is either an object id (or WKT geometry) string, or an (lng, lat) tuple.
+Point = Union[str, tuple[float, float]]
+
+
+def _point_to_str(point: Point) -> str:
+    if isinstance(point, str):
+        return point
+    lng, lat = point
+    return f"{lng},{lat}"
+
+
+def _points_param(points: str | Iterable[Point]) -> str:
+    """Format a list of points for a query parameter.
+
+    A pre-formatted string is passed through unchanged. Otherwise, the API
+    uses '|' to separate coordinate pairs and ',' to separate object ids, so
+    an iterable must be all-coordinates or all-ids; mixed lists must be
+    formatted by the caller and passed in as a raw string.
+    """
+    if isinstance(points, str):
+        return points
+    items = list(points)
+    if not items:
+        raise ValueError("points must not be empty")
+    if all(isinstance(p, str) for p in items):
+        return ",".join(items)  # type: ignore[arg-type]
+    if all(not isinstance(p, str) for p in items):
+        return "|".join(_point_to_str(p) for p in items)
+    raise ValueError(
+        "cannot mix object ids and (lng, lat) tuples in one list; "
+        "pass a pre-formatted string instead"
+    )
+
+
+def _clean_params(params: dict[str, Any]) -> dict[str, Any]:
+    """Drop None values and render booleans the way the API expects."""
+    cleaned: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        cleaned[key] = value
+    return cleaned

visicom_api/_endpoints.py

@@ -0,0 +1,166 @@
+"""Query-parameter builders for every Visicom Data API endpoint.
+
+This mixin is shared by the sync and async clients so the endpoint naming,
+point formatting, and None-stripping logic lives in exactly one place.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Literal
+
+from ._base import Point, _clean_params, _point_to_str, _points_param
+
+Format = Literal["json", "csv"]
+Lang = Literal["uk", "ru", "en"]
+Mode = Literal["driving", "driving-shortest", "direct"]
+SnapMode = Literal["driving", "walking"]
+Order = Literal["relevance", "distance"]
+
+PathParams = tuple[str, dict[str, Any]]
+
+
+class _Endpoints:
+    default_lang: Lang
+
+    def _geocode_path_params(
+        self,
+        *,
+        lang: Lang | None,
+        format: Format,
+        text: str | None,
+        word_text: str | None,
+        categories: str | None,
+        categories_exclude: str | None,
+        near: Point | None,
+        radius: float | None,
+        intersect: Point | None,
+        contains: Point | None,
+        order: Order | None,
+        zoom: int | None,
+        limit: int | None,
+        country: str | None,
+        boost_country: str | None,
+    ) -> PathParams:
+        path = f"{lang or self.default_lang}/geocode.{format}"
+        params = _clean_params(
+            {
+                "text": text,
+                "word_text": word_text,
+                "categories": categories,
+                "categories_exclude": categories_exclude,
+                "near": _point_to_str(near) if near is not None else None,
+                "radius": radius,
+                "intersect": _point_to_str(intersect) if intersect is not None else None,
+                "contains": _point_to_str(contains) if contains is not None else None,
+                "order": order,
+                "zoom": zoom,
+                "limit": limit,
+                "country": country,
+                "boost_country": boost_country,
+            }
+        )
+        return path, params
+
+    def _feature_path_params(
+        self,
+        *,
+        ids: str | Iterable[str],
+        lang: Lang | None,
+        format: Format,
+        geometry: bool,
+    ) -> PathParams:
+        id_param = ids if isinstance(ids, str) else ",".join(ids)
+        path = f"{lang or self.default_lang}/feature/{id_param}.{format}"
+        params = _clean_params({"geometry": None if geometry else "no"})
+        return path, params
+
+    def _distance_path_params(
+        self,
+        *,
+        origin: Point,
+        destination: Point,
+        waypoints: str | Iterable[Point] | None,
+        locks: str | Iterable[Point] | None,
+        mode: Mode,
+        geometry: Literal["no", "path"],
+        accuracy: float | None,
+    ) -> PathParams:
+        params = _clean_params(
+            {
+                "origin": _point_to_str(origin),
+                "destination": _point_to_str(destination),
+                "waypoints": _points_param(waypoints) if waypoints is not None else None,
+                "locks": _points_param(locks) if locks is not None else None,
+                "mode": mode,
+                "geometry": geometry,
+                "accuracy": accuracy,
+            }
+        )
+        return "core/distance.json", params
+
+    def _distancematrix_path_params(
+        self,
+        *,
+        origins: str | Iterable[Point],
+        destinations: str | Iterable[Point],
+        locks: str | Iterable[Point] | None,
+        mode: Mode,
+    ) -> PathParams:
+        params = _clean_params(
+            {
+                "origins": _points_param(origins),
+                "destinations": _points_param(destinations),
+                "locks": _points_param(locks) if locks is not None else None,
+                "mode": mode,
+            }
+        )
+        return "core/distancematrix.json", params
+
+    def _tsp_path_params(
+        self,
+        *,
+        waypoints: str | Iterable[Point],
+        round_trip: bool,
+        locks: str | Iterable[Point] | None,
+        mode: Mode,
+    ) -> PathParams:
+        params = _clean_params(
+            {
+                "waypoints": _points_param(waypoints),
+                "round_trip": round_trip,
+                "locks": _points_param(locks) if locks is not None else None,
+                "mode": mode,
+            }
+        )
+        return "core/tsp.json", params
+
+    def _snaptoroad_path_params(
+        self,
+        *,
+        points: str | Iterable[Point],
+        interpolate: bool,
+        mode: SnapMode,
+        separate: bool,
+    ) -> PathParams:
+        params = _clean_params(
+            {
+                "points": _points_param(points),
+                "interpolate": interpolate,
+                "mode": mode,
+                "separate": separate,
+            }
+        )
+        return "core/snaptoroad.json", params
+
+    def _location_path_params(
+        self, *, start: Point, azimut: float, distance: float, format: Format
+    ) -> PathParams:
+        params = _clean_params(
+            {"start": _point_to_str(start), "azimut": azimut, "distance": distance}
+        )
+        return f"core/location.{format}", params
+
+    def _buffer_path_params(self, *, near: Point, radius: float, format: Format) -> PathParams:
+        params = _clean_params({"near": _point_to_str(near), "radius": radius})
+        return f"core/buffer.{format}", params

visicom_api/async_client.py

@@ -0,0 +1,197 @@
+"""Asynchronous client for the Visicom Data API."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from types import TracebackType
+from typing import Any, Literal, cast
+
+import httpx
+
+from ._base import BASE_URL, Point
+from ._endpoints import Format, Lang, Mode, Order, SnapMode, _Endpoints
+from .exceptions import raise_for_status
+from .models import (
+    BufferResponse,
+    DistanceMatrixResponse,
+    DistanceResult,
+    GeocodeResult,
+    LocationResponse,
+    SnapToRoadResult,
+    TspResponse,
+)
+
+
+class AsyncVisicomClient(_Endpoints):
+    """Asynchronous client for the Visicom Data API.
+
+    Example:
+        async with AsyncVisicomClient(api_key="YOUR_API_KEY") as client:
+            result = await client.geocode(text="Київ, Хрещатик, 26")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        lang: Lang = "uk",
+        base_url: str = BASE_URL,
+        timeout: float = 10.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.api_key = api_key
+        self.default_lang: Lang = lang
+        self._client = client or httpx.AsyncClient(base_url=base_url, timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncVisicomClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def _get(self, path: str, params: dict[str, Any]) -> Any:
+        response = await self._client.get(path, params={**params, "key": self.api_key})
+        raise_for_status(response)
+        return response.json()
+
+    async def geocode(
+        self,
+        *,
+        text: str | None = None,
+        word_text: str | None = None,
+        categories: str | None = None,
+        categories_exclude: str | None = None,
+        near: Point | None = None,
+        radius: float | None = None,
+        intersect: Point | None = None,
+        contains: Point | None = None,
+        order: Order | None = None,
+        zoom: int | None = None,
+        limit: int | None = None,
+        country: str | None = None,
+        boost_country: str | None = None,
+        lang: Lang | None = None,
+        format: Format = "json",
+    ) -> GeocodeResult:
+        """Search objects by name, or reverse-geocode near a point. See /geocode docs."""
+        path, params = self._geocode_path_params(
+            lang=lang,
+            format=format,
+            text=text,
+            word_text=word_text,
+            categories=categories,
+            categories_exclude=categories_exclude,
+            near=near,
+            radius=radius,
+            intersect=intersect,
+            contains=contains,
+            order=order,
+            zoom=zoom,
+            limit=limit,
+            country=country,
+            boost_country=boost_country,
+        )
+        return cast(GeocodeResult, await self._get(path, params))
+
+    async def feature(
+        self,
+        ids: str | Iterable[str],
+        *,
+        lang: Lang | None = None,
+        format: Format = "json",
+        geometry: bool = True,
+    ) -> GeocodeResult:
+        """Fetch full geometry and attributes for up to 250 object ids."""
+        path, params = self._feature_path_params(
+            ids=ids, lang=lang, format=format, geometry=geometry
+        )
+        return cast(GeocodeResult, await self._get(path, params))
+
+    async def distance(
+        self,
+        origin: Point,
+        destination: Point,
+        *,
+        waypoints: str | Iterable[Point] | None = None,
+        locks: str | Iterable[Point] | None = None,
+        mode: Mode = "driving",
+        geometry: Literal["no", "path"] = "no",
+        accuracy: float | None = None,
+    ) -> DistanceResult:
+        """Compute a route/distance between two points."""
+        path, params = self._distance_path_params(
+            origin=origin,
+            destination=destination,
+            waypoints=waypoints,
+            locks=locks,
+            mode=mode,
+            geometry=geometry,
+            accuracy=accuracy,
+        )
+        return cast(DistanceResult, await self._get(path, params))
+
+    async def distancematrix(
+        self,
+        origins: str | Iterable[Point],
+        destinations: str | Iterable[Point],
+        *,
+        locks: str | Iterable[Point] | None = None,
+        mode: Mode = "driving",
+    ) -> DistanceMatrixResponse:
+        """Compute a distance matrix between up to 25x25 points."""
+        path, params = self._distancematrix_path_params(
+            origins=origins, destinations=destinations, locks=locks, mode=mode
+        )
+        return cast(DistanceMatrixResponse, await self._get(path, params))
+
+    async def tsp(
+        self,
+        waypoints: str | Iterable[Point],
+        *,
+        round_trip: bool = True,
+        locks: str | Iterable[Point] | None = None,
+        mode: Mode = "driving",
+    ) -> TspResponse:
+        """Solve the travelling-salesman ordering for up to 50 waypoints."""
+        path, params = self._tsp_path_params(
+            waypoints=waypoints, round_trip=round_trip, locks=locks, mode=mode
+        )
+        return cast(TspResponse, await self._get(path, params))
+
+    async def snaptoroad(
+        self,
+        points: str | Iterable[Point],
+        *,
+        interpolate: bool = False,
+        mode: SnapMode = "driving",
+        separate: bool = False,
+    ) -> SnapToRoadResult:
+        """Snap up to 250 GNSS points onto the road network."""
+        path, params = self._snaptoroad_path_params(
+            points=points, interpolate=interpolate, mode=mode, separate=separate
+        )
+        return cast(SnapToRoadResult, await self._get(path, params))
+
+    async def location(
+        self, start: Point, azimut: float, distance: float, *, format: Format = "json"
+    ) -> LocationResponse:
+        """Direct geodesic problem: find a point given a start, azimuth, and distance."""
+        path, params = self._location_path_params(
+            start=start, azimut=azimut, distance=distance, format=format
+        )
+        return cast(LocationResponse, await self._get(path, params))
+
+    async def buffer(
+        self, near: Point, radius: float, *, format: Format = "json"
+    ) -> BufferResponse:
+        """Build a buffer polygon (up to 10000 m) around a point/geometry/object."""
+        path, params = self._buffer_path_params(near=near, radius=radius, format=format)
+        return cast(BufferResponse, await self._get(path, params))

visicom_api/client.py

@@ -0,0 +1,195 @@
+"""Synchronous client for the Visicom Data API."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from types import TracebackType
+from typing import Any, Literal, cast
+
+import httpx
+
+from ._base import BASE_URL, Point
+from ._endpoints import Format, Lang, Mode, Order, SnapMode, _Endpoints
+from .exceptions import raise_for_status
+from .models import (
+    BufferResponse,
+    DistanceMatrixResponse,
+    DistanceResult,
+    GeocodeResult,
+    LocationResponse,
+    SnapToRoadResult,
+    TspResponse,
+)
+
+
+class VisicomClient(_Endpoints):
+    """Synchronous client for the Visicom Data API.
+
+    Example:
+        with VisicomClient(api_key="YOUR_API_KEY") as client:
+            result = client.geocode(text="Київ, Хрещатик, 26")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        lang: Lang = "uk",
+        base_url: str = BASE_URL,
+        timeout: float = 10.0,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.api_key = api_key
+        self.default_lang: Lang = lang
+        self._client = client or httpx.Client(base_url=base_url, timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> VisicomClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _get(self, path: str, params: dict[str, Any]) -> Any:
+        response = self._client.get(path, params={**params, "key": self.api_key})
+        raise_for_status(response)
+        return response.json()
+
+    def geocode(
+        self,
+        *,
+        text: str | None = None,
+        word_text: str | None = None,
+        categories: str | None = None,
+        categories_exclude: str | None = None,
+        near: Point | None = None,
+        radius: float | None = None,
+        intersect: Point | None = None,
+        contains: Point | None = None,
+        order: Order | None = None,
+        zoom: int | None = None,
+        limit: int | None = None,
+        country: str | None = None,
+        boost_country: str | None = None,
+        lang: Lang | None = None,
+        format: Format = "json",
+    ) -> GeocodeResult:
+        """Search objects by name, or reverse-geocode near a point. See /geocode docs."""
+        path, params = self._geocode_path_params(
+            lang=lang,
+            format=format,
+            text=text,
+            word_text=word_text,
+            categories=categories,
+            categories_exclude=categories_exclude,
+            near=near,
+            radius=radius,
+            intersect=intersect,
+            contains=contains,
+            order=order,
+            zoom=zoom,
+            limit=limit,
+            country=country,
+            boost_country=boost_country,
+        )
+        return cast(GeocodeResult, self._get(path, params))
+
+    def feature(
+        self,
+        ids: str | Iterable[str],
+        *,
+        lang: Lang | None = None,
+        format: Format = "json",
+        geometry: bool = True,
+    ) -> GeocodeResult:
+        """Fetch full geometry and attributes for up to 250 object ids."""
+        path, params = self._feature_path_params(
+            ids=ids, lang=lang, format=format, geometry=geometry
+        )
+        return cast(GeocodeResult, self._get(path, params))
+
+    def distance(
+        self,
+        origin: Point,
+        destination: Point,
+        *,
+        waypoints: str | Iterable[Point] | None = None,
+        locks: str | Iterable[Point] | None = None,
+        mode: Mode = "driving",
+        geometry: Literal["no", "path"] = "no",
+        accuracy: float | None = None,
+    ) -> DistanceResult:
+        """Compute a route/distance between two points."""
+        path, params = self._distance_path_params(
+            origin=origin,
+            destination=destination,
+            waypoints=waypoints,
+            locks=locks,
+            mode=mode,
+            geometry=geometry,
+            accuracy=accuracy,
+        )
+        return cast(DistanceResult, self._get(path, params))
+
+    def distancematrix(
+        self,
+        origins: str | Iterable[Point],
+        destinations: str | Iterable[Point],
+        *,
+        locks: str | Iterable[Point] | None = None,
+        mode: Mode = "driving",
+    ) -> DistanceMatrixResponse:
+        """Compute a distance matrix between up to 25x25 points."""
+        path, params = self._distancematrix_path_params(
+            origins=origins, destinations=destinations, locks=locks, mode=mode
+        )
+        return cast(DistanceMatrixResponse, self._get(path, params))
+
+    def tsp(
+        self,
+        waypoints: str | Iterable[Point],
+        *,
+        round_trip: bool = True,
+        locks: str | Iterable[Point] | None = None,
+        mode: Mode = "driving",
+    ) -> TspResponse:
+        """Solve the travelling-salesman ordering for up to 50 waypoints."""
+        path, params = self._tsp_path_params(
+            waypoints=waypoints, round_trip=round_trip, locks=locks, mode=mode
+        )
+        return cast(TspResponse, self._get(path, params))
+
+    def snaptoroad(
+        self,
+        points: str | Iterable[Point],
+        *,
+        interpolate: bool = False,
+        mode: SnapMode = "driving",
+        separate: bool = False,
+    ) -> SnapToRoadResult:
+        """Snap up to 250 GNSS points onto the road network."""
+        path, params = self._snaptoroad_path_params(
+            points=points, interpolate=interpolate, mode=mode, separate=separate
+        )
+        return cast(SnapToRoadResult, self._get(path, params))
+
+    def location(
+        self, start: Point, azimut: float, distance: float, *, format: Format = "json"
+    ) -> LocationResponse:
+        """Direct geodesic problem: find a point given a start, azimuth, and distance."""
+        path, params = self._location_path_params(
+            start=start, azimut=azimut, distance=distance, format=format
+        )
+        return cast(LocationResponse, self._get(path, params))
+
+    def buffer(self, near: Point, radius: float, *, format: Format = "json") -> BufferResponse:
+        """Build a buffer polygon (up to 10000 m) around a point/geometry/object."""
+        path, params = self._buffer_path_params(near=near, radius=radius, format=format)
+        return cast(BufferResponse, self._get(path, params))

visicom_api/exceptions.py

@@ -0,0 +1,49 @@
+"""Exceptions raised by the Visicom API client."""
+
+from __future__ import annotations
+
+import httpx
+
+
+class VisicomError(Exception):
+    """Base exception for all errors raised by this library."""
+
+
+class VisicomAPIError(VisicomError):
+    """Raised when the Visicom API returns a non-success response."""
+
+    def __init__(
+        self, message: str, status_code: int, response: httpx.Response | None = None
+    ) -> None:
+        super().__init__(f"[{status_code}] {message}")
+        self.status_code = status_code
+        self.response = response
+
+
+class VisicomAuthError(VisicomAPIError):
+    """Raised on 401/403 responses - invalid, missing, or expired API key."""
+
+
+class VisicomRateLimitError(VisicomAPIError):
+    """Raised on 429 responses - request quota exceeded."""
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Translate an httpx response into a VisicomAPIError subclass if needed."""
+    if response.is_success:
+        return
+
+    message = response.text
+    try:
+        payload = response.json()
+        if isinstance(payload, dict):
+            message = str(payload.get("message") or payload.get("error") or message)
+    except ValueError:
+        pass
+
+    status = response.status_code
+    if status in (401, 403):
+        raise VisicomAuthError(message, status, response)
+    if status == 429:
+        raise VisicomRateLimitError(message, status, response)
+    raise VisicomAPIError(message, status, response)

visicom_api/models.py

@@ -0,0 +1,329 @@
+"""Typed response shapes for the Visicom Data API, derived from the official
+OAS3 spec (https://api.visicom.ua/data-api/5.0/openapi.yaml).
+
+These are TypedDicts, not runtime-validated models: they document the shape
+of the parsed JSON so callers get autocomplete/mypy checking without adding a
+validation dependency. Fields are `total=False` throughout because the spec's
+own `required` lists are inconsistent with its `properties` lists in several
+places (e.g. AdmDistrict requires `settlement_class` but never defines it).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict, Union
+
+BBox = list[float]  # [min_lng, min_lat, max_lng, max_lat]
+
+
+class PointGeometry(TypedDict, total=False):
+    type: Literal["Point"]
+    coordinates: list[float]  # [lng, lat]
+
+
+class LineStringGeometry(TypedDict, total=False):
+    type: Literal["LineString"]
+    coordinates: list[list[float]]
+
+
+class PolygonGeometry(TypedDict, total=False):
+    type: Literal["Polygon"]
+    coordinates: list[list[list[float]]]
+
+
+class MultiPolygonGeometry(TypedDict, total=False):
+    type: Literal["MultiPolygon"]
+    coordinates: list[list[list[list[float]]]]
+
+
+Geometry = Union[PointGeometry, LineStringGeometry, PolygonGeometry, MultiPolygonGeometry]
+
+
+class NamedRef(TypedDict, total=False):
+    """An `{id, name}` reference to another object, e.g. an admin subdivision."""
+
+    id: str
+    name: str
+
+
+# --- /geocode and /feature `properties`, one per `categories` value ---------
+
+
+class AdmCountryProperties(TypedDict, total=False):
+    name: str
+    categories: Literal["adm_country"]
+    lang: str
+    country_code: str
+    admin_center: str
+    admin_center_id: str
+    admin_center_url: str
+    copyright: str
+    levels1: list[NamedRef]
+
+
+class AdmDistrictProperties(TypedDict, total=False):
+    name: str
+    type: str
+    categories: Literal["adm_district"]
+    country_code: str
+    country: str
+    lang: str
+    level1: str
+    level1_id: str
+    level2: str
+    level2_id: str
+    level3: str
+    level3_id: str
+    settlement: str
+    settlement_id: str
+    settlement_type: str
+    settlement_class: str
+    copyright: str
+    settlement_url: str
+    level1_url: str
+    level2_url: str
+    level3_url: str
+
+
+class AdmLevel1Properties(TypedDict, total=False):
+    name: str
+    categories: Literal["adm_level1"]
+    country_code: str
+    country: str
+    lang: str
+    admin_center: str
+    admin_center_id: str
+    admin_center_url: str
+    copyright: str
+    levels2: list[NamedRef]
+
+
+class AdmLevel2Properties(TypedDict, total=False):
+    name: str
+    categories: Literal["adm_level2"]
+    country_code: str
+    country: str
+    lang: str
+    level1: str
+    level1_id: str
+    level1_url: str
+    copyright: str
+    levels3: list[NamedRef]
+
+
+class AdmLevel3Properties(TypedDict, total=False):
+    name: str
+    categories: Literal["adm_level3"]
+    country_code: str
+    country: str
+    lang: str
+    level1: str
+    level1_id: str
+    level2: str
+    level2_id: str
+    level2_url: str
+    copyright: str
+
+
+# `class` is a Python keyword, so this one uses the functional TypedDict form.
+AdmSettlementProperties = TypedDict(
+    "AdmSettlementProperties",
+    {
+        "name": str,
+        "categories": Literal["adm_settlement"],
+        "country_code": str,
+        "country": str,
+        "lang": str,
+        "level1": str,
+        "level1_id": str,
+        "level2": str,
+        "level2_id": str,
+        "level3": str,
+        "level3_id": str,
+        "type": str,
+        "class": str,
+        "copyright": str,
+    },
+    total=False,
+)
+
+
+class AdrAddressProperties(TypedDict, total=False):
+    name: str
+    categories: Literal["adr_address"]
+    street_id: str
+    lang: str
+    street: str
+    street_type: str
+    zone: str
+    settlement_id: str
+    settlement: str
+    settlement_type: str
+    height: float
+    copyright: str
+    settlement_url: str
+    street_url: str
+    # Undocumented in the OAS3 spec, but present in live API responses.
+    country: str
+    country_code: str
+    postal_code: str
+    relevance: float
+
+
+class AdrStreetProperties(TypedDict, total=False):
+    name: str
+    name_en: str
+    categories: Literal["adr_street"]
+    country_code: str
+    country: str
+    lang: str
+    settlement_id: str
+    zone: str
+    type: str
+    settlement: str
+    settlement_type: str
+    settlement_class: str
+    address: list[NamedRef]
+    copyright: str
+    settlement_url: str
+
+
+class PoiProperties(TypedDict, total=False):
+    name: str
+    categories: str  # one of many poi_* ids, see GET /categories
+    lang: str
+    address: str
+    address_info: str
+    country_code: str
+    creation_data: str
+    creator: str
+    description: str
+    email: str
+    phones: list[str]
+    site_url: str
+    star: float
+    vitrine: str
+    w24hours: bool
+    icon: int
+    photo1: int
+    photo2: int
+    photo3: int
+    copyright: str
+
+
+FeatureProperties = Union[
+    AdmCountryProperties,
+    AdmDistrictProperties,
+    AdmLevel1Properties,
+    AdmLevel2Properties,
+    AdmLevel3Properties,
+    AdmSettlementProperties,
+    AdrAddressProperties,
+    AdrStreetProperties,
+    PoiProperties,
+]
+
+
+class GeoFeature(TypedDict, total=False):
+    """A single object as returned by /geocode or /feature."""
+
+    type: Literal["Feature"]
+    id: str
+    bbox: BBox
+    geo_centroid: PointGeometry
+    geometry: Geometry
+    properties: Any  # narrow with FeatureProperties / cast() based on properties["categories"]
+    url: str
+
+
+class FeatureCollection(TypedDict, total=False):
+    """Wraps multiple results. The OAS3 spec names this field `feature`
+    (singular), but real responses use the GeoJSON-standard `features`
+    (verified against the live API); the spec is wrong here."""
+
+    type: Literal["FeatureCollection"]
+    features: list[GeoFeature]
+
+
+GeocodeResult = Union[GeoFeature, FeatureCollection]
+
+
+# --- /distance ---------------------------------------------------------------
+
+
+class DistanceNoGeometryResponse(TypedDict, total=False):
+    distance: int
+
+
+class _RoutePoint(TypedDict, total=False):
+    type: Literal["Point"]
+    coordinates: list[float]
+
+
+class DistancePathProperties(TypedDict, total=False):
+    origin: _RoutePoint
+    destination: _RoutePoint
+    distance: float
+
+
+class DistancePathResponse(TypedDict, total=False):
+    type: Literal["Feature"]
+    geometry: LineStringGeometry
+    properties: DistancePathProperties
+    bbox: BBox
+
+
+DistanceResult = Union[DistanceNoGeometryResponse, DistancePathResponse]
+
+
+# --- /distancematrix -----------------------------------------------------------
+
+
+class DistanceMatrixCell(TypedDict, total=False):
+    distance: int
+    # Not in the OAS3 schema, but present in the docs' example responses.
+    status: str
+
+
+class DistanceMatrixResponse(TypedDict, total=False):
+    rows: list[list[DistanceMatrixCell]]
+
+
+# --- /tsp ----------------------------------------------------------------------
+
+
+class TspWaypoint(TypedDict, total=False):
+    index: int
+
+
+class TspResponse(TypedDict, total=False):
+    list: list[TspWaypoint]
+
+
+# --- /buffer and /location -------------------------------------------------------
+
+BufferResponse = PolygonGeometry
+LocationResponse = PointGeometry
+
+
+# --- /snaptoroad -----------------------------------------------------------------
+
+
+class SnapPointFeature(TypedDict, total=False):
+    type: Literal["Feature"]
+    geometry: PointGeometry
+    bbox: BBox
+
+
+class SnapLineFeature(TypedDict, total=False):
+    type: Literal["Feature"]
+    geometry: LineStringGeometry
+    bbox: BBox
+
+
+class SnapFeatureCollection(TypedDict, total=False):
+    type: Literal["FeatureCollection"]
+    features: list[SnapPointFeature | SnapLineFeature]
+    bbox: BBox
+
+
+SnapToRoadResult = Union[SnapPointFeature, SnapLineFeature, SnapFeatureCollection]

visicom_api_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: visicom-api-client
+Version: 0.1.0
+Summary: Unofficial sync/async Python client for the Visicom Data API
+Project-URL: Homepage, https://api.visicom.ua/uk/products/data-api/data-api-references
+Author: Your Name
+License: MIT
+Keywords: api-client,geocoding,gis,visicom
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# visicom-api-client
+
+Неофіційний Python-клієнт для [Visicom Data API](https://api.visicom.ua/uk/products/data-api/data-api-references) (геокодування, маршрутизація, буфери, прив'язка до доріг).
+
+## Встановлення
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Використання
+
+Синхронно:
+
+```python
+from visicom_api import VisicomClient
+
+with VisicomClient(api_key="YOUR_API_KEY") as client:
+    result = client.geocode(text="Київ, Хрещатик, 26")
+    print(result)
+
+    route = client.distance((30.42612, 50.45111), (30.44946, 50.45682))
+    print(route["distance"])
+```
+
+Асинхронно:
+
+```python
+import asyncio
+from visicom_api import AsyncVisicomClient
+
+
+async def main() -> None:
+    async with AsyncVisicomClient(api_key="YOUR_API_KEY") as client:
+        result = await client.geocode(categories="poi_restaurant", near=(30.5113, 50.4550), radius=300)
+        print(result)
+
+
+asyncio.run(main())
+```
+
+Точки (`origin`, `near`, `waypoints`, ...) можна передавати як:
+- ідентифікатор об'єкта: `"POIA1KIGKN"`
+- координати: `(lng, lat)` кортеж
+- список точок для `waypoints`/`locks`/`origins`/`destinations`/`points`: `[(lng, lat), ...]` або список id
+- заздалегідь відформатований рядок (наприклад, WKT-геометрія)
+
+## Обробка помилок
+
+```python
+from visicom_api import VisicomAuthError, VisicomRateLimitError, VisicomAPIError
+
+try:
+    client.geocode(text="...")
+except VisicomAuthError:
+    ...  # невірний або відсутній ключ
+except VisicomRateLimitError:
+    ...  # перевищено ліміт запитів
+except VisicomAPIError as e:
+    ...  # інша помилка API, e.status_code
+```
+
+## Розробка
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+mypy src
+pytest
+```

visicom_api_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+visicom_api/__init__.py,sha256=wheLVj2FJ-KV_5TqJ8fhVSePhjy_XEMrtwVyQjvbXEc,1322
+visicom_api/_base.py,sha256=ctnMWf9JgT0cEl74LRefFdQSuXiDVUqZXHKQ4VYVAR0,1832
+visicom_api/_endpoints.py,sha256=mM1nPFnrdnQmaEXKwd3zcIhk8S7XmXsLkE52QvMYWCY,5336
+visicom_api/async_client.py,sha256=1zBaWNsCXgC1WFb9Uxht21krp6sSTWQa3lMl9TZ6oMM,6597
+visicom_api/client.py,sha256=QvFFvPqi2wNvTtotFC81D-zmf5NfzYzDMjEdQ73lo_s,6401
+visicom_api/exceptions.py,sha256=ds2MP3ojH6Fvsk8QTG2t7oKZm4RMrNjf-Z9ullFXlSE,1455
+visicom_api/models.py,sha256=k5bsKKw6a5-DuPNlP62_pPy33QsGbVUIQLgdMQQOUwI,7789
+visicom_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+visicom_api_client-0.1.0.dist-info/METADATA,sha256=eC7sf3fgCGCDtRON0v5rSa9EXAe4QIzPiogLJK_X7n0,2804
+visicom_api_client-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+visicom_api_client-0.1.0.dist-info/RECORD,,

visicom_api_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any