HH.ru Vacancy Recommendations Scraper

Полнофункциональный Python скрипт для автоматизированной выгрузки и анализа вакансий с HH.ru.

🎯 Основные возможности

• Поиск похожих вакансий на основе ядра ID вакансий
• Выгрузка избранного всех вакансий соискателя
• Обогащение данных — получение полной информации о каждой вакансии
• Кэширование API запросов для избежания rate limits при отладке
• Ранжирование по релевантности — автоматическая сортировка результатов
• Resilient обработка — логирование ошибок без прерывания работы
• Excel экспорт — удобный формат для передачи в LLM

📋 Требования

• Python 3.12.4+
• Anaconda (рекомендуется)
• Активированное приложение на dev.hh.ru с OAuth токеном
• Переменная окружения
  HH_ACCESS_TOKEN
  или
  .env
  файл

🚀 Быстрый старт

1. Установка зависимостей

2. Настройка OAuth токена

1. Зарегистрируйте приложение на dev.hh.ru:
   • нужно будет выбрать
   • после модерации там появятся ,
2. Внесите в .env
   • HH_MY_CLIENT_ID=
   • HH_MY_CLIENT_SECRET=
   • HH_MY_REDIRECT_URI=
3. Запустите скрипт hh_token.py для получения токена - он будет добавлен в конец файла .env

3. Запуск скрипта

📖 Сценарии использования

Сценарий 1: Ядро вакансий + похожие

Используйте, если у вас есть Excel с ID интересующих вакансий, и нужно найти похожие:

Структура входящего файла:

Результат: Excel со всеми похожими вакансиями, отсортированными по релевантности.

Сценарий 2: Выгрузить избранное

Используйте для скачивания всех вакансий из избранного:

Результат: Excel со всеми вакансиями из избранного.

Сценарий 3: Ядро + CV пометки

Используйте, когда нужно отметить, для каких CV релевантна каждая вакансия:

Результат: Excel с пометками, для каких CV файлов рекомендована каждая вакансия.

📊 Структура результирующего Excel

🔧 Команды и параметры

💾 Кэширование

Используйте кэш для ускорения разработки и избегания rate limits:

Как это работает:

• При первом запуске: скрипт обращается к API и сохраняет ответы в
  ./cache
• При повторных запусках: читает данные из кэша (намного быстрее)
• Очистка кэша:
  rm -rf ./cache

📝 Примеры использования

Полный пример с наибольшим числом опций

Минимальный пример

С .env файлом

🛠️ Архитектура

HHAPIClient

Класс для взаимодействия с HH API с поддержкой кэширования:

VacancyProcessor

Класс для обработки вакансий:

⚙️ Логирование

Скрипт выводит логи в консоль:

2025-12-18 12:43:10,123 - __main__ - INFO - OAuth токен успешно загружен
2025-12-18 12:43:11,456 - __main__ - INFO - Начало обработки 5 вакансий ядра
2025-12-18 12:43:12,789 - __main__ - WARNING - Ошибка при загрузке похожих для вакансии 123456: HTTP 404
2025-12-18 12:43:20,123 - __main__ - INFO - Сформировано 45 строк результатов

Уровни логирования:

• INFO
  — основная информация
• WARNING
  — предупреждения (ошибки при обработке отдельных вакансий)
• ERROR
  — критические ошибки

❓ Частые вопросы

Q: Что, если токен истёк?
A: Получите новый токен через OAuth авторизацию и обновите переменную окружения.

Q: Как ускорить выполнение?
A: Используйте кэш:

Q: Что делать, если результаты пусты?
A: Проверьте, что ID вакансий правильные. Откройте их напрямую в браузере:

Q: Сколько времени занимает выполнение?
A: Выгрузка избранного (~50 вакансий): 10-30 сек. Поиск похожих (5 ядер): 1-3 минуты.

Tests

1. Установите зависимости

pip install pytest pytest-cov

2. Запустите тесты

pytest test_hh_vacancy_scraper.py -v

3. С покрытием

pytest test_hh_vacancy_scraper.py --cov=hh_vacancy_scraper --cov-report=html

📚 Дополнительные ресурсы

• Документация HH API
• Раздел OAuth
• GitHub репозиторий HH API
• SETUP_GUIDE.md — детальная инструкция по установке
• FAQ_TROUBLESHOOTING.md — решение проблем

📄 Файлы в проекте

• hh_vacancy_scraper.py
  — основной скрипт
• README.md
  — этот файл
• SETUP_GUIDE.md
  — руководство по установке и настройке
• FAQ_TROUBLESHOOTING.md
  — FAQ и решение проблем
• .env
  — файл с переменными окружения (создайте сами)

🔐 Безопасность

• Не коммитьте .env файл в Git (добавьте в
  .gitignore
  )
• Хранейте токен приватно (используйте переменные окружения)
• Отзовите токен если он скомпрометирован (в личном кабинете dev.hh.ru)

💡 Примеры использования с LLM

После выгрузки данных в Excel, передайте в LLM:

📞 Поддержка и обратная связь

• Ошибки в коде: проверьте FAQ_TROUBLESHOOTING.md
• Вопросы об API HH: api@hh.ru
• Проблемы с авторизацией: dev.hh.ru

📄 Лицензия

Скрипт предоставляется в образовательных целях. Используйте в соответствии с условиями использования HH API.

Автор: AI Assistant
Дата: 2025-12-18
Версия: 1.0
Python: 3.12.4+