Парсер гео-баз компаний (2ГИС / Яндекс.Карты)

Цель: из связки «город + категория» собрать структурированную базу компаний с контактами (телефон/сайт/почта/адрес) для B2B-лидгена пользователя. Всё локально, без облачных сервисов.

Когда применять

• «собери базу компаний / организаций / фирм из 2ГИС (или Яндекс.Карт)»
• «вытащи контакты / телефоны по категории X в городе Y»
• «база для обзвона / холодных продаж / рассылки»
• «парсинг 2гис / выгрузка 2gis»

НЕ для: разведки одного конкретного игрока (это competitor-intel), стратегии выбора ниши (это strategy-researcher). Этот скил — только сбор + чистка контактов. Кого собирать (ICP, какие категории/города) — приходит из брифа, не выдумывается здесь.

Статус каналов (проверено 2026-06-24)

• 2ГИС — РАБОЧИЙ. parser-2gis v1.2.1 установлен (py -m pip show parser-2gis). Гонит реальный Chrome, отдаёт CSV/XLSX/JSON.
• Яндекс.Карты — ЗАГЛУШКА. Готового локального канала нет (рабочий код — сторонние репозитории на GitHub). См. раздел «Яндекс.Карты» — два пути активации.

Среда

• parser-2gis — console-script parser-2gis (он же Parser2GIS) на PATH. Зависимости лёгкие (psutil, pychrome, pydantic, requests, xlsxwriter — без PyQt).
• Google Chrome — обязателен (обычно C:\Program Files\Google\Chrome\Application\chrome.exe). Парсер драйвит его через CDP; сам парсинг идёт через системный Chrome, поэтому при прокси/VPN учитывай, что Chrome ходит напрямую.
• Python 3.14 (py, не python). Движок чистки — scripts/merge_normalize.py.
• Переустановка при нужде: py -m pip install --retries 5 --timeout 60 parser-2gis. GUI-версия (точка-клик для пользователя): py -m pip install "parser-2gis[gui]", запуск parser-2gis без аргументов.

CLI parser-2gis (снят с --help, не с вики)

parser-2gis -i URL [URL ...] -o PATH -f {csv,xlsx,json} [опции]

Главные флаги:

• -i, --url URL — поисковый URL 2ГИС (можно несколько). Формат URL — см. ниже, это главная грабля.
• -o, --output-path PATH — куда писать.
• -f, --format {csv,xlsx,json} — формат. Для базы бери csv (или xlsx если пользователю в Excel).
• --parser.max-records N — лимит записей (на тесты ставь 3-5, на боевой сбор — сколько надо).
• --writer.csv.remove-duplicates yes — встроенный дедуп внутри прогона.
• --writer.csv.add-rubrics yes — добавить рубрики.
• --chrome.binary_path PATH — путь к Chrome (обычно не нужен, находит сам).
• --chrome.headless {yes,no} — см. «Режимы запуска».
• --chrome.disable-images {yes,no} — yes быстрее, но иногда ленивый список не догружается.
• --parser.delay_between_clicks МС — увеличить при рваной сети.

Схема CSV на выходе (богатая): Наименование, Описание, Рубрики, Адрес, Индекс, Район, Город, Часы работы, Рейтинг, Кол-во отзывов, Широта, Долгота, 2GIS URL, Тип + динамические колонки контактов (Телефон/Сайт/Почта/соцсети — появляются, когда у фирм есть эти данные).

URL-рецепт 2ГИС (ОБЯЗАТЕЛЬНО, иначе 0 записей)

Плоский https://2gis.ru/<city>/search/<запрос> → ошибка «Bound is incorrect» (2ГИС требует границы карты). Лечение — добавить вьюпорт карты:

https://2gis.ru/<city_slug>/search/<URL-encoded запрос>/?m=<lon>%2C<lat>%2F<zoom>

Пример (Москва, стоматологии): https://2gis.ru/moscow/search/стоматологии/?m=37.62%2C55.75%2F12

• city_slug — латиницей: moscow, spb, kazan, krasnodar, ekaterinburg, novosibirsk и т.д. Список и центры городов — references/city_viewpoints.md.
• m=lon,lat/zoom — центр карты (долгота, широта) и зум. zoom 11-13 = масштаб города.
• Самый надёжный способ получить URL — открыть 2gis.ru в браузере, ввести запрос, подвинуть карту на нужный район и скопировать URL из адресной строки (он уже содержит вьюпорт). Так пользователь может задать точную географию.

Режимы запуска (важно)

• Штатный — headful в сессии пользователя. 2ГИС режет headless (антибот → 0 записей), а headful из процесса агента падает (нет интерактивного рабочего стола). Поэтому боевой сбор гонит пользователь в своём окне (команда ниже), или через GUI parser-2gis[gui] (точка-клик, без флагов). Это аналог «логина под VPN» — шаг, который инструмент готовит, а жмёт пользователь.
• Автоном-попытка — headless. Скил может попробовать --chrome.headless yes сам; если CSV вышел с 0 строк данных (только заголовок) → это антибот, эскалируй пользователю: «дай прогнать headful в твоей сессии» + готовая команда.

Боевая команда (пользователь запускает у себя, headful):

parser-2gis -i "<URL из адресной строки 2gis>" -o "C:\путь\base_raw.csv" -f csv ^
  --parser.max-records 500 --chrome.headless no --writer.csv.remove-duplicates yes --writer.csv.add-rubrics yes

Пайплайн (что делает скил)

1. Разобрать бриф: город(а), категория(и) = поисковые запросы, нужный объём, нужен ли только с телефоном. Если география размытая — попросить пользователя скопировать URL из 2gis (см. рецепт).
2. Собрать URL(ы) по рецепту (city_slug + запрос + ?m=). На каждую пару город×категория — свой URL.
3. Прогнать parser-2gis в нужном режиме (по умолчанию — отдать команду пользователю headful; либо headless-попытка). Сырые CSV — в inputs/ сессии.
4. Слить + почистить: py scripts/merge_normalize.py OUT.csv inputs/*.csv [--only-with-phone]. Кросс-файловый дедуп (по имя+телефон), нормализация телефонов в +7XXXXXXXXXX, авто-детект колонок по содержимому (телефон/сайт/почта — регэкспом, не по кириллическим заголовкам). Пишет OUT.csv + OUT.summary.md (счётчики, % с телефоном/сайтом/почтой).
5. Положить в vault (см. ниже) + короткий отчёт пользователю: сколько собрано, % с телефоном, путь.
6. Хендофф (если бриф просит): базу можно отдать дальше — competitor-intel (разведка по топ-N из базы), task-author/ghostwriter (скрипт обзвона / письмо). Это уже работа оркестратора, скил только готовит базу.

Куда класть результат

• Сырые CSV прогонов → <VAULT_ROOT>/08-Работа-Claude/<session>/inputs/
• Чистая база + summary → корень <VAULT_ROOT>/08-Работа-Claude/<session>/ (имя base_<город>_<категория>_<дата>.csv латиницей).
• Если у клиента есть своя рабочая папка — продублировать туда; уточнять у оркестратора.

Яндекс.Карты (ЗАГЛУШКА — два пути активации)

Готового рабочего канала нет. Когда дойдут руки — приоритет такой:

1. Официальный Places/Geosuggest API Яндекса (РЕКОМЕНДУЮ — легально и стабильно). Нужен бесплатный ключ (developer.tech.yandex.ru, JS API + Places). Тогда я пишу мини-граббер на requests против их API — без браузера, без антибота, через системный VPN. Это чище любого скрейпа. Блокер — только получение ключа пользователем (нужен его логин).
2. Скрейп через клон GitHub-репо. git clone https://github.com/chernyshov-dp/YMapsGrabber (собирает организации в области поиска) или artemsteshenko/parser_maps. Дальше тот же merge_normalize.py для чистки (он схемо-независим).

При запросе на Яндекс — не молчать, а выдать эти два варианта и спросить, какой активировать.

Грабли

• .py — без кириллических литералов (Windows-консоль в cp1251 бьёт их). merge_normalize.py детектит колонки по содержимому, поэтому Cyrillic-заголовки не хардкодит. В консоль — только ASCII.
• Пути с кириллицей в командах parser-2gis иногда ломаются → клади сырые CSV в ASCII-путь, потом переноси.
• disable-images yes ускоряет, но при рваной сети список не догружается → если мало записей, гони disable-images no + delay_between_clicks 1000.
• Не ставь огромный max-records на первом прогоне — сначала 5-10 для проверки URL, потом боевой объём.

Этика / право (коротко)

2ГИС/Яндекс в ToS запрещают автоскрейп. Применять только для авторизованного B2B-лидгена пользователя (публичные контакты организаций): умеренный темп, не перепродавать сырьё, помнить про 152-ФЗ (контакты юрлиц — ок, персональные данные физлиц не собирать). Официальный API Яндекса (путь 1) этих рисков лишён — предпочтительнее.

Связь с оркестратором

Триггер брифа «собери базу компаний из 2ГИС/Яндекс» → оркестратор вызывает этот скил (Skill tool), а не плодит general-purpose. Скил готовит базу; разведку/тексты поверх неё — отдельными агентами во вторую волну.