artwist-polyakov/yandex-webmaster

yandex-webmaster

Работа с Yandex Webmaster API v4. Управление сайтами, анализ индексации, поисковые запросы, переобход страниц, ссылки, фиды.

Config

Требуется YANDEX_WEBMASTER_TOKEN в config/.env. Scope: webmaster:hostinfo + webmaster:verify. Инструкция: config/README.md.

Для alice.sh (Share of Voice, без публичного API) дополнительно нужен SESSION_ID — cookie из браузера. Подробности в config/README.md и references/ALICE_EFFICIENCY.md.

Philosophy

1. Cache-first — список сайтов, user_id кешируются надолго. Отчёты кешируются по ключу host+params. Диагностика, квоты, статусы — всегда live.
2. Context window hygiene — stdout ограничен 30 строками. Полные данные в TSV/файл. Кеш доступен через grep/rg.
3. Host resolution — все скрипты принимают --host <domain> (поиск по кешу hosts.tsv) или --host-id <id> (прямой ID). Первый вызов hosts.sh автоматически кеширует список.
4. No destructive ops — скилл не удаляет сайты, сайтмапы и фиды. Только чтение и добавление.

Workflow

STOP! Перед любым анализом:

1. Получи список сайтов:

   bash scripts/hosts.sh
   

2. Спроси пользователя (если сайт не очевиден из контекста):

   "О каком сайте идёт речь?
   Укажите домен или host_id из списка."
   

   Для поиска по кешу:

   bash scripts/hosts.sh --search "example"
   

3. Получи сводку по сайту:

   bash scripts/summary.sh --host example.com
   

4. Запускай нужные отчёты по задаче пользователя.

Scripts

Общий паттерн вызова:

bash scripts/<script>.sh --host <domain> [--action <action>] [params...]

Управление сайтами

| Script | Description | Key params | |--------|-------------|------------| | hosts.sh | Список сайтов | --search "text", --no-cache | | host_info.sh | Инфо о сайте + владельцы | — | | add_site.sh | Добавить сайт | --url <url> | | verify.sh | Верификация сайта | --action get\|start, --method DNS\|HTML_FILE\|META_TAG |

Статистика сайта

| Script | Description | Key params | |--------|-------------|------------| | summary.sh | Сводка: SQI, страницы, проблемы | — | | sqi_history.sh | История SQI | --date-from, --date-to | | diagnostics.sh | Проблемы сайта (live) | — |

Поисковые запросы

| Script | Description | Key params | |--------|-------------|------------| | popular_queries.sh | Топ запросов | --order-by, --device, --limit | | queries_history.sh | История запросов | --query-id (опц.), --device | | query_analytics.sh | Расширенная аналитика (POST) | --text-indicator, --filter-*, --region-ids |

Индексация

| Script | Description | Key params | |--------|-------------|------------| | indexing.sh | История/сэмплы индексации | --action history\|samples | | important_urls.sh | Важные URL | --action list\|history, --url | | archive_export.sh | Экспорт всех страниц | --action start\|status, --task-id |

Страницы в поиске

| Script | Description | Key params | |--------|-------------|------------| | insearch.sh | Страницы в выдаче | --action history\|samples | | search_events.sh | Появление/исчезновение | --action history\|samples |

Переобход

| Script | Description | Key params | |--------|-------------|------------| | recrawl.sh | Переобход URL | --action submit\|status\|list\|quota, --url, --task-id |

Ссылки

| Script | Description | Key params | |--------|-------------|------------| | internal_links.sh | Битые внутренние ссылки | --action samples\|history, --indicator | | external_links.sh | Внешние ссылки | --action samples\|history |

Сайтмапы

| Script | Description | Key params | |--------|-------------|------------| | sitemaps.sh | Управление сайтмапами | --action list\|user-list\|info\|add\|recrawl-limit\|recrawl |

Alice / Share of Voice (SSR scraping)

| Script | Description | Key params | |--------|-------------|------------| | alice.sh | Эффективность в Алисе: SoV timeline, конкуренты, запросы где сайт есть/нет | --action summary\|sov\|competitors\|with-site\|without-site\|fetch, --no-cache |

⚠ Нет публичного API — данные парсятся из window._initData HTML-страницы. Требует SESSION_ID cookie в config/.env. См. references/ALICE_EFFICIENCY.md.

Фиды и PRO

| Script | Description | Key params | |--------|-------------|------------| | feeds.sh | YML-фиды | --action list\|add\|change\|add-status, --type, --region-ids | | search_export.sh | PRO SERP экспорт | --action dates\|limits\|start\|status | | regions.sh | Справочник регионов | --filter "москва" |

Общие параметры

| Param | Description | |-------|-------------| | --host <domain> | Домен/URL сайта (поиск по hosts.tsv) | | --host-id <id> | Прямой host_id (формат: http:example.com:80) | | --action <act> | Подкоманда скрипта | | --date-from | Начало периода YYYY-MM-DD (history: default 90 дней назад) | | --date-to | Конец периода YYYY-MM-DD | | --limit N | Число записей | | --offset N | Смещение | | --no-cache | Пропустить кеш |

Кеш-стратегия

Кеш в cache/:

• user_id.txt — ID пользователя (permanent)
• hosts.json + hosts.tsv — список сайтов (permanent, инвалидируется при add/verify)
• host_*/queries/*.tsv — результаты запросов (session, hash-keyed)
• host_*/indexing/*.tsv — данные индексации (session)
• host_*/insearch/*.tsv — данные о поиске (session)
• host_*/links/*.tsv — данные о ссылках (session)
• host_*/alice/init.json — распарсенный alice объект, переиспользуется всеми action'ами alice.sh (refresh: --no-cache или --action fetch)
• Диагностика, квоты, статусы переобхода — не кешируются (always live)

Расширенные сценарии

• Добавление и верификация сайтов
• Поисковые запросы и аналитика
• Управление сайтмапами
• Статистика сайта и индексация
• Страницы в поиске
• Переобход страниц
• Битые внутренние ссылки
• Внешние ссылки
• YML-фиды
• PRO SERP экспорт
• Alice / Share of Voice (scraping)
• Расписание врачей (спецификация)

Лимиты API

• Query Analytics: 10 000 запросов/час на домен
• Скрипты автоматически обрабатывают 429 (Retry-After ≤ 60s → retry, иначе fail)
• Лимит сайтов: 1703 на аккаунт
• Лимит фидов: 5000 на сайт, 50 в batch
• Лимит export: макс. 100 комбинаций дат+URL