Relavio Docs

Appearance

Python SDK ​

Официальный Python SDK Relavio пока не выпущен. Для интеграции используйте REST API напрямую через requests, httpx или другой HTTP-клиент.

Эта страница показывает пример небольшого Python-клиента для поиска, подсказок и событий аналитики.

Установка HTTP-клиента ​

Примеры ниже используют requests.

bash
pip install requests

Базовый клиент ​

python
from __future__ import annotations

from typing import Any
import requests


class RelavioClient:
    def __init__(self, api_key: str, base_url: str = "https://relavio.su/api/v1") -> None:
        self.api_key = api_key
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update({
            "Accept": "application/json",
            "Content-Type": "application/json",
            "api-key": api_key,
        })

    def search(self, payload: dict[str, Any]) -> dict[str, Any]:
        return self._post("search", payload)

    def suggests(self, payload: dict[str, Any]) -> dict[str, Any]:
        return self._post("search/suggests", payload)

    def event(self, payload: dict[str, Any]) -> dict[str, Any]:
        return self._post("search/events", payload)

    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
        response = self.session.post(
            f"{self.base_url}/{path}",
            json=payload,
            timeout=10,
        )

        if not response.ok:
            raise RuntimeError(f"Relavio API error {response.status_code}: {response.text}")

        return response.json()

Поиск товаров ​

python
client = RelavioClient("YOUR_API_KEY")

result = client.search({
    "query": "iphone",
    "page": 1,
    "per_page": 20,
    "withFilters": True,
    "filters": {
        "brand": ["Apple"],
        "price": {
            "from": 50000,
            "to": 120000,
        },
    },
})

products = result["data"]["products"]

Подсказки ​

python
suggests = client.suggests({
    "query": "iph",
    "session_id": "session-123",
})

suggestions = suggests["data"]["suggestions"]
categories = suggests["data"]["categories"]
products = suggests["data"]["products"]

Событие аналитики ​

python
from uuid import uuid4

client.event({
    "event_id": str(uuid4()),
    "event_type": "click",
    "search_id": "search-123",
    "session_id": "session-123",
    "external_id": "iphone-15-128",
    "product_name": "iPhone 15 128GB Black",
    "position": 1,
    "page": 1,
    "price": 99990,
    "currency": "RUB",
    "metadata": {
        "source": "python-client",
    },
})

Асинхронный пример с httpx ​

Если приложение асинхронное, можно использовать httpx.

bash
pip install httpx
python
import httpx


async def search_products(api_key: str, query: str) -> dict:
    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.post(
            "https://relavio.su/api/v1/search",
            headers={
                "Accept": "application/json",
                "Content-Type": "application/json",
                "api-key": api_key,
            },
            json={
                "query": query,
                "page": 1,
                "per_page": 20,
            },
        )

        response.raise_for_status()
        return response.json()

Обработка ошибок ​

Для надежной интеграции обрабатывайте HTTP-статусы:

  • 401 - API-ключ отсутствует или неверный;
  • 402 - превышен лимит или недостаточно баланса;
  • 422 - ошибка валидации payload;
  • 500 - внутренняя ошибка сервера.

Пример:

python
try:
    result = client.search({"query": "iphone"})
except RuntimeError as error:
    print(error)

Подробнее: Ошибки API.

Хранение API-ключа ​

Не храните ключ в исходном коде. Используйте переменные окружения.

bash
export RELAVIO_API_KEY="YOUR_API_KEY"
python
import os

client = RelavioClient(os.environ["RELAVIO_API_KEY"])

Когда использовать Python-интеграцию ​

Python-клиент полезен для:

  • серверных приложений;
  • внутренних инструментов;
  • ETL-процессов;
  • тестирования Search API;
  • отправки событий аналитики из backend-систем.

Для браузерного поиска на сайте обычно проще использовать готовый JavaScript-виджет Relavio Search.

Связанные разделы ​