serp-rank-tracking

Снятие позиций и слепков выдачи

Выдача платная у всех трёх источников, и цена считается за запрос к провайдеру, а не за вызов инструмента. Отсюда весь порядок действий ниже.

Перед первым вызовом

1. <сервер>_auth_status — есть ли ключи. Нет — спросить у пользователя и сохранить через <сервер>_set_credentials, не просить лезть в файлы руками.
2. xmlstock_balance / xmlriver_balance — бесплатные, показывают остаток. Перед прогоном по большому пулу проверить баланс: на середине списка деньги кончаются молча.

Какой источник брать

• xmlstock — дешевле и проще, один запрос = одна страница выдачи. Берёт Google и Яндекс, умеет serp_features (featured snippet, PAA, related, sitelinks) и подсветки text_bolds.
• xmlriver — дороже (каждые 10 результатов = 1 платный запрос, depth добирается пагинацией), но умеет то, чего нет у xmlstock: флаг ai_overview, гео по городу (location), проверку индексации, «Вопросы по теме», Maps.
• aparser — свой сервер, оплата не за запрос, а за прокси; см. навык aparser-operations.

Стоимость: считать до, а не после

depth — главный множитель. У xmlriver depth: 100 по одному запросу — это 10 списаний, а по пулу из 200 ключей — 2000. Если задача звучит как «мы в топ-10 или нет», хватает depth: 10. Полная сотня нужна только когда позиция заведомо низкая и её надо найти.

При прогоне по пулу: озвучить пользователю оценку («200 запросов × depth 10 ≈ 200 списаний») до запуска, а не после.

Регионы

• Яндекс: числовой region (lr). Москва 213, Питер 2, Екатеринбург 54, Россия целиком 225. Регион меняет выдачу сильно — без него результат бессмысленен для локального бизнеса.
• Google у xmlstock: region (uule/страна) + searchDomain.
• Google у xmlriver: location понимает город строкой («Moscow»), country выводится из города сам. Это единственный из двух, кто даёт городской таргетинг Google.

Чтение ответа

• truncated: true — выдача кончилась раньше запрошенного depth. Это не ошибка и не повод повторять запрос с большей глубиной: результатов физически меньше.
• found — сколько всего нашёл движок, count — сколько вернулось.
• position — позиция в органике. При includeAds: true реклама идёт отдельно и в органическую нумерацию не вмешивается.
• excludeAggregators: true выкидывает маркетплейсы и агрегаторы (Avito, Ozon, Wildberries, Циан…). Список переопределяется переменной XMLSTOCK_EXCLUDE_DOMAINS / XMLRIVER_EXCLUDE_DOMAINS. Полезно, когда ищут «живых» конкурентов, а не площадки.