UnihraClient

from unihra import UnihraClient

Конструктор

UnihraClient(
    api_key: str,
    base_url: str = "https://unihra.ru",
    max_retries: int = 0,
    storage_dir: str = "unihra_results",
)

Параметр	Описание
api_key	Ваш API-ключ Unihra
base_url	Переопределение базового URL API (для self-hosted)
max_retries	Число повторов HTTP при серверных ошибках (429, 5xx)
storage_dir	Директория для вывода analyze_and_save()

---

Основной анализ

analyze()

def analyze(
    own_page: str,
    competitors: List[str],
    queries: Optional[List[str]] = None,
    lang: Literal['ru', 'en'] = 'ru',
    url_cookies: Optional[Dict[str, str]] = None,
    triplet_analysis: bool = False,
    verbose: bool = False,
) -> Dict[str, Any]

Запускает полный анализ и блокирует выполнение до завершения.

Возвращает: словарь с ключами umbrella_analysis, block_comparison, ngrams_analysis, anchors_analysis, page_structure, опционально triplets_analysis и _meta.

---

analyze_stream()

def analyze_stream(
    own_page: str,
    competitors: List[str],
    queries: Optional[List[str]] = None,
    lang: str = 'ru',
    url_cookies: Optional[Dict[str, str]] = None,
    triplet_analysis: bool = False,
) -> Generator[Dict, None, None]

Возвращает генератор словарей SSE-событий. У каждого события есть ключ state: PENDING, PROCESSING, PROGRESS, SUCCESS или FAILURE.

---

analyze_and_save()

def analyze_and_save(**kwargs) -> Dict[str, Any]

Запускает analyze(**kwargs) и сохраняет каждую секцию как отдельный JSON-файл в storage_dir/{task_id}/.

Возвращает: манифест с analysis_id и files (мап секция → абсолютный путь).

---

Доступ к данным

get_dataframe()

def get_dataframe(
    result: Dict[str, Any],
    section: str = "block_comparison",
) -> pd.DataFrame

Конвертирует секцию результата в pandas DataFrame. Требует pandas.

Поддерживаемые секции:

Секция	Описание
block_comparison	Данные TF-IDF слов
umbrella_analysis	Зонтичный анализ (старый ключ semantic_context_analysis принимается как fallback)
ngrams_analysis	Данные n-грамм фраз
anchors_analysis	Данные текстов якорей
page_structure	Распакованная структура страниц
triplets_analysis	Граф знаний — одна строка на факт
triplets_gaps	Отсутствующие темы — одна строка на пробел

---

get_page_structure()

def get_page_structure(task_id: str) -> List[Dict[str, Any]]

Получает данные структуры страниц из API по task_id. Вызывается автоматически в analyze().

---

Экспорт

save_report()

def save_report(
    result: Dict[str, Any],
    filename: str = "report.xlsx",
    style_output: bool = True,
) -> None

Сохраняет результат в .xlsx (многолистовая книга с цветовой разметкой) или .csv (только block_comparison). Требует openpyxl и pandas.

---

Аккаунт и шеринг

get_limits()

def get_limits() -> Dict[str, Any]

Возвращает текущие лимиты и баланс ключа.

{
    "plan": "pro",
    "daily_limit": 5000,
    "used_today": 12,
    "remaining_today": 4988,
    "rate_limit": 6000
}

---

list_analyses()

def list_analyses() -> List[Dict[str, Any]]

Возвращает все анализы, сохранённые под этим ключом.

---

get_analysis()

def get_analysis(task_id: str) -> Dict[str, Any]

Получает ранее созданный результат анализа. Анализы хранятся 90 дней.

---

share_analysis()

def share_analysis(task_id: str) -> Dict[str, Any]

Создаёт публичную ссылку для шеринга.

Возвращает: {"share_url": "https://unihra.ru/s/abc123"}

---

unshare_analysis()

def unshare_analysis(task_id: str) -> None

Отзывает ссылку шеринга. Возвращает None при успехе.

---

health()

def health() -> Dict[str, Any]

Проверяет доступность API. Возвращает {"status": "ok"} или выбрасывает UnihraConnectionError.