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
```
