xmlriver-serp-research

XMLRiver: выдача поиска и Wordstat

Навык собирает исходные данные. Он не выбирает ключи, не оценивает коммерческий смысл, не меняет кампании и не заменяет рекламный кабинет. Порядок работы с Директом задаёт единый навык; методы официального Wordstat описаны в справочнике Wordstat.

Когда использовать

XMLRiver — равноправная альтернатива Yandex Cloud, а не его замена. Выбирайте:

• Yandex Cloud (Search API, Wordstat v2) — если у вас есть ключ и каталог облака: это официальные интерфейсы Яндекса;
• XMLRiver — если облака нет, квоты официального Wordstat (10 запросов в секунду, 100 в час) не хватает на объём задачи или нужна выдача Google.

XMLRiver — сторонний платный сервис. Он разбирает живую выдачу и интерфейс Wordstat, это не официальный API Яндекса и не Google. Условия использования у вас свои; решение о платном расходе принимает пользователь.

Сборщики модуля выбирают путь сами: --provider yandex-cloud, --provider xmlriver или auto (по умолчанию). В режиме auto путь выбирается по переменным окружения: берётся тот, для которого задан доступ (облако — YANDEX_SEARCH_API_KEY, YANDEX_SEARCH_IAM_TOKEN или YANDEX_WORDSTAT_API_KEY, XMLRiver — XMLRIVER_USER и XMLRIVER_KEY). Если заданы оба, не задан ни один или передан файл доступа (--credentials-file, --config), скрипт остановится и попросит указать --provider явно: молча переключаться между платными путями нельзя.

Что нужно заранее

1. Свой аккаунт XMLRiver с положительным балансом. В личном кабинете, раздел «Настройки сбора», задайте параметры сбора: без этого ссылка сбора может быть недоступна. Если в кабинете включён доступ по IP, добавьте свой адрес, иначе будет ошибка 45.
2. Доступ в переменных окружения процесса: XMLRIVER_USER и XMLRIVER_KEY (допустим старый синоним XMLRIVER_USER_ID) либо закрытый файл с правами 0600 через --credentials-file. Ключ не передавать аргументом, не печатать, не сохранять в журналах, отчётах, таблицах и выгрузках.
3. Папка запуска вне репозитория. В ней появятся журнал, сырые ответы и таблицы.

Для первого знакомства в наборе есть общий демо-доступ: флаг --use-demo-key. Его баланс общий для всех пользователей и ограничен, скрипт ставит с ним потолок 2 руб. за запуск. Для работы заведите свой аккаунт: демо может закончиться в любой момент.

До платных запросов

1. Выполните info: баланс, цена за 1000 запросов, число потоков, доступность систем. Не считайте старые цены и лимиты действующими.
2. Подготовьте задания: запрос × регион × система × страница. Выдача Яндекса — регион Яндекса (region_id, справочник «Регионы для загрузки фидов» в документации Яндекса); Google — страна, при необходимости местоположение и код языка из справочников XMLRiver (geo.csv, countries.xlsx, langs.xlsx, domains.xlsx).
3. Выполните plan (без сети): число заданий, оценка стоимости, SHA-256 плана. Новый крупный платный пакет покажите пользователю, если разрешение на расход не дано.
4. Не добавляйте платные опции (--ai) без необходимости: надбавку get_info не показывает. Для collect --ai обязательно --ai-price-per-1000 — надбавка по вашему тарифу, она входит в оценку и потолок; с демо-доступом --ai запрещён.

Сбор

Команды выполняются из каталога навыка (рядом с этим файлом лежит scripts/xmlriver_collect.py).

python3 scripts/xmlriver_collect.py info
python3 scripts/xmlriver_collect.py plan    --kind serp --jobs-file jobs.tsv --output-dir RUN --engine yandex --ads on
python3 scripts/xmlriver_collect.py collect --kind serp --jobs-file jobs.tsv --output-dir RUN --engine yandex --ads on \
    --approve-plan-sha256 <SHA из plan> --max-cost-rub <потолок> --probe 3
python3 scripts/xmlriver_collect.py export  --kind serp --jobs-file jobs.tsv --output-dir RUN --engine yandex --ads on

Файл заданий выдачи — TSV в формате serp-job-template.tsv единого порядка: job_id, search_query, region_id, необязательные page, engine, device, enabled, layer, purpose, search_region, notes, google_country, google_lang, google_loc, google_domain. Один и тот же файл подходит и сборщику Yandex Cloud: лишние колонки не мешают.

• Перед сетевым вызовом задание записывается в журнал. Каждый ответ сохраняется отдельным файлом с SHA-256 и квитанцией; значения доступа в сохранённом ответе заменяются на [REDACTED].
• Повторный запуск того же плана не отправляет успешные задания снова. Код 15 («результатов нет») — состояние empty, не ошибка и не повторяется.
• Временные ошибки 101, 110, 111, 500 повторяются отдельным запуском --retry-errors (по умолчанию только эти коды; --only-codes сужает список). Прежние попытки сохраняются.
• Задание с неизвестным исходом (inflight: обрыв, таймаут) автоматически не отправляется повторно — запрос мог быть оплачен. Посмотрите команду inflight; снять задание можно только с --acknowledge-possible-charge.
• 31, 42, 45 (доступ), 115 (слишком много параллельных запросов, блокировка на 10 минут), 200 (нет денег) и HTTP 429 останавливают пакет. Параллельность держите ниже лимита потоков из info. Два collect в одном каталоге одновременно запустить нельзя: второй останавливается до сети, а каждое задание захватывается атомарно, поэтому один запрос не оплачивается дважды. new_requests в итоге — число фактически отправленных запросов.

Особенности систем

• Яндекс: страницы с нуля, groupby=10, регион числом, domain=ru, lang=ru. Позиция считается только среди результатов contenttype=organic. Для второй и следующих страниц абсолютная позиция (abs_rank_state=verified) ставится лишь при непрерывной цепочке успешных страниц от нулевой, 10 органических результатов на каждой предыдущей, без пересечений адресов и без смены исправленного запроса. Иначе позиция «не доказана»: номер страницы × 10 ранг не доказывает.
• Google: страницы с единицы (скрипт принимает номер с нуля и сам прибавляет единицу), страна и язык из справочников. Местоположение loc для крупных городов бывало источником устойчивой ошибки 500 — проверьте пробой, при ошибке работайте на уровне страны.
• Одинаково названные параметры различаются: lr у Яндекса — регион числом, у Google — язык кодом; domain у Яндекса — строка, у Google — числовой идентификатор.

Реклама

• Яндекс: --ads on добавляет рекламные блоки (y_topads, y_bottomads; правый блок — --yandex-right-ads).
• Google: документация XMLRiver обещает рекламные блоки, но в проверках автора набора (сентябрь–октябрь 2026, в том числе проба 23.10.2026) Google рекламу не возвращал. Перед пакетом сделайте одиночную пробу на заведомо коммерческом запросе; пустой результат не доказывает отсутствие рекламы конкурентов.
• Число объявлений в снимке — не охват рынка. Ноль объявлений в ответе не означает, что рекламы нет в другом месте и в другой момент. Пустые поля сначала проверьте на разборе, потом делайте выводы.
• Сохраняются исходные поля объявления: url (отображаемый адрес), adsurl (рекламный переход Google), заголовок, текст, быстрые ссылки. Конечная страница не подменяется догадкой: landing-unresolved, пока она не подтверждена отдельной проверкой. По рекламным ссылкам скрипт не переходит.
• Заголовок или текст может содержать процентно кодированные теги выделения (%3Cb%3E). В сырых полях они сохраняются; для чтения есть отдельные колонки title_clean и snippet_clean.

Wordstat через XMLRiver

python3 scripts/xmlriver_collect.py plan    --kind wordstat --masks-file masks.tsv --output-dir RUN --regions 225 --pagetypes words,history
python3 scripts/xmlriver_collect.py collect --kind wordstat --masks-file masks.tsv --output-dir RUN --regions 225 --pagetypes words,history \
    --approve-plan-sha256 <SHA> --max-cost-rub <потолок>
python3 scripts/xmlriver_collect.py export  --kind wordstat --masks-file masks.tsv --output-dir RUN --regions 225 --pagetypes words,history

• Лимита «100 запросов в час» нет; лимит — число потоков аккаунта и ошибки 110/115. Лимиты официального API на XMLRiver не переносятся, и наоборот.
• Каждая маска стоит два платных запроса: words (популярные и похожие запросы) и history (динамика и общее число). В пробе 23.10.2026 страница words вернула до 759 строк на маску.
• Схема ответа другая: popular и associations (числа строками, в тексте операторы +). Общее число по маске даёт только history (totalValue, за предыдущий месяц). export пишет в RUN/raw_bundle/ файлы top_requests_*.json и dynamics_*.json и _manifest.json в формате облачного сборщика; отчёты волны, спроса и сезонности находят файлы через манифест. При нескольких регионах у каждого свой каталог raw_bundle/region_<номер>/, чтобы отчёт волны не смешивал регионы. Повторный export пересобирает каталог целиком. Строка с неверной частотностью не теряется молча: файл помечается partial в манифесте, строка уходит в wordstat_row_errors.tsv, а команда завершается кодом 2. Даты динамики — по московскому времени. Ответ без ожидаемых полей (popular или graph) считается ошибкой, а не успехом. Если history не собирали, totalCount в файле отсутствует, а не равен нулю.
• Нет аналога дерева регионов и распределения по регионам: регион передаётся одним числом, для нескольких регионов создаются отдельные задания.
• Числа XMLRiver и официального Wordstat не складывать и не сравнивать без пометки источника: это разные продукты (provider в каждом файле).
• Интервалы динамики: month — не менее 3 полных месяцев, week — не менее 3 недель с понедельника по воскресенье, day — не менее 3 дней, конечный день не сегодня. Скрипт проверяет это до запроса; по умолчанию берёт 6 последних завершённых месяцев.

Разбор и выводы

• Органика (serp_results.tsv, колонки как у сборщика Yandex Cloud), колдунщики (feature_rows.tsv) и реклама (ad_rows.tsv) выгружаются отдельно. Если в плане обе системы, таблицы пишутся по одной на систему (serp_results_yandex.tsv, serp_results_google.tsv и т. д.): прежние отчёты группируют только по запросу и региону и смешали бы Яндекс с Google. Регион в таблице — фактически использованный (для Яндекса по умолчанию 225). В каждой строке: исходный запрос и задание, регион, система, устройство, время ответа, положение, путь к сырому файлу и его SHA-256.
• Различайте «блока нет в ответе», «поля нет», «ответ с ошибкой» и «задание не выполнено». Статистику покрытия считайте по успешным заданиям и показывайте пропуски, ошибки, период и географию.
• Выводы вида «конкурентов в рекламе нет» по разовому снимку запрещены.
• Смысловая обработка частотностей и ключей — дальше по единому навыку; здесь автоматический отбор не выполняется.

Проверка перед сдачей

1. Повторный collect по тому же плану даёт ноль новых запросов.
2. export строит таблицы только из сохранённых ответов, без сети; контрольные суммы совпадают.
3. Число заданий по состояниям (success, empty, error, inflight, pending) сходится с планом; расход и баланс до и после записаны (разница общего баланса может включать чужие запросы на том же аккаунте).
4. В отчёте нет ключей, полных адресов запросов и клиентских данных.
5. Расход на XMLRiver указан отдельно от расходов Yandex Cloud (контроль расходов облака относится только к Yandex Cloud).