visicom-api-client 0.1.0__tar.gz

visicom_api_client-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy src
+      - name: Run tests
+        run: pytest

visicom_api_client-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage

visicom_api_client-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,70 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "visicom-api-client"
+version = "0.1.0"
+description = "Unofficial sync/async Python client for the Visicom Data API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Your Name" }]
+keywords = ["visicom", "geocoding", "gis", "api-client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.20",
+    "ruff>=0.4",
+    "mypy>=1.8",
+]
+
+[project.urls]
+Homepage = "https://api.visicom.ua/uk/products/data-api/data-api-references"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/visicom_api"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+packages = ["visicom_api"]

visicom_api_client-0.1.0/scripts/smoke_test.py

@@ -0,0 +1,46 @@
+"""Manual smoke test against the real Visicom Data API.
+
+Not part of the pytest suite (network + real API key required). Run with:
+    VISICOM_API_KEY=... python scripts/smoke_test.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from visicom_api import VisicomClient  # noqa: E402
+
+
+def main() -> None:
+    api_key = os.environ.get("VISICOM_API_KEY")
+    if not api_key:
+        raise SystemExit("Set VISICOM_API_KEY environment variable first")
+
+    with VisicomClient(api_key=api_key) as client:
+        print("=== geocode (single expected result, limit=1) ===")
+        geocode_result = client.geocode(text="Київ, Хрещатик, 26", limit=1)
+        print("type:", type(geocode_result).__name__)
+        print("top-level keys:", list(geocode_result.keys()))
+        print(json.dumps(geocode_result, ensure_ascii=False, indent=2)[:1500])
+
+        print("\n=== geocode (multiple results, no limit) ===")
+        many_result = client.geocode(
+            categories="poi_restaurant", near=(30.5113, 50.4550), radius=300
+        )
+        print("type:", type(many_result).__name__)
+        print("top-level keys:", list(many_result.keys()))
+
+        print("\n=== distancematrix (check for 'status' field) ===")
+        matrix = client.distancematrix(
+            origins=[(30.36277, 50.51605), (30.49667, 50.49508)],
+            destinations=[(30.36277, 50.51605), (30.49667, 50.49508)],
+        )
+        print(json.dumps(matrix, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

visicom_api_client-0.1.0/src/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_client-0.1.0/src/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_client-0.1.0/src/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