БэкендData и ИИPython

HeadHunter API на Python: собираем вакансии и считаем самые частые навыки

Получаем вакансии через HeadHunter API на Python, загружаем навыки из карточек, считаем частотность и сохраняем честный отчёт для выбранного города.

Кодик

Автор

6 мин чтения

HeadHunter API можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. Открытый API hh.ru позволяет искать вакансии по тексту и региону, а затем получать подробную карточку с массивом key_skills. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.

Список вакансий не содержит всех навыков, выборка ограничена и меняется каждый день, поэтому одна страница поиска не является статистикой рынка. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте скрипт, который берёт первые вакансии Python-стажёров в Москве, загружает карточки и печатает десять самых частых навыков. Проверка: запрос возвращает JSON, детали загружены с паузой, пустые key_skills не ломают подсчёт, а отчёт содержит размер выборки и дату.

1Соберите минимум

вызвать GET /vacancies с text, area и per_page. Не расширяйте проект до первого успешного запуска.

2Увидьте данные

карточка содержит key_skills или пустой список. Проверяйте значение, а не отсутствие ошибки.

3Измените правило

После успеха добавьте второй город и сравните долю SQL, Git и Docker. Так копирование станет практикой.

Как устроен учебный проект HeadHunter API

Первый запрос получает список вакансий, второй этап загружает детали по URL каждой карточки, Counter считает нормализованные названия навыков. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.

ЭтапДействиеПроверяемый результат
Поисквызвать GET /vacancies с text, area и per_pageответ содержит items и found
Детализагрузить URL каждой вакансиикарточка содержит key_skills или пустой список
Подсчётнормализовать названия и обновить Counterодин навык не раздваивается из-за регистра
Отчётвывести top-10, дату и размер выборкирезультат можно воспроизвести

Контрольные точки: поиск, детали, подсчёт и отчёт. Следующий шаг начинается после совпадения с ожидаемым результатом.

Путь данных в проекте HeadHunter API
От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Зафиксируйте первый успех Отправьте один запрос с per_page=3 и обязательным User-Agent. Проверьте status_code, found и названия вакансий до цикла деталей. Сохраните команду запуска и ожидаемый вывод.

Собираем рабочий пример шаг за шагом

Материал сверялся с официальной документацией 2 ноября 2026 года. Создайте окружение, установите requests и задайте информативный заголовок User-Agent с названием учебного проекта. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

from collections import Counter
from datetime import date
import time
import requests

BASE = "https://api.hh.ru"
HEADERS = {"User-Agent": "codik-learning-project/1.0 (student@example.com)"}

def fetch_json(url: str, **params):
    response = requests.get(url, params=params, headers=HEADERS, timeout=20)
    response.raise_for_status()
    return response.json()

search = fetch_json(
    f"{BASE}/vacancies",
    text="Python стажёр",
    area=1,
    per_page=20,
    page=0,
)

skills = Counter()
for item in search["items"]:
    vacancy = fetch_json(item["url"])
    for skill in vacancy.get("key_skills", []):
        name = skill["name"].strip().lower()
        if name:
            skills[name] += 1
    time.sleep(0.15)

print("Дата:", date.today().isoformat())
print("Вакансий в выборке:", len(search["items"]))
for name, count in skills.most_common(10):
    print(f"{name:24} {count}")
Что должно произойти после запуска
  • Терминал показывает дату, число обработанных карточек и десять навыков с частотой.
  • Вакансия без key_skills учитывается в размере выборки, но не создаёт ошибку KeyError.
  • Повторный запуск даёт тот же предсказуемый результат.
  • Пустой ввод получает понятное сообщение вместо падения.

Главная функция принимает явный вход и возвращает результат, который можно проверить отдельно от интерфейса. Найдите в примере вход, проверку и место формирования результата.

Хрупкий и проверяемый вариант HeadHunter API
Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

Search endpoint возвращает краткие карточки и URL деталей. key_skills находятся в полной вакансии, поэтому для точного подсчёта нужен второй ограниченный цикл запросов. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. API просит передавать User-Agent. Не увеличивайте частоту запросов бесконечно и не называйте двадцать вакансий полной картиной рынка.

ЧастьЗа что отвечаетЧто проверить
Поискзадаёт запрос, город и страницуfound и items читаются отдельно
Деталидобавляют key_skills каждой карточкиошибка одной вакансии журналируется
Counterсчитает нормализованные названияотчёт содержит размер выборки

Результат зависит от формулировки text, региона, даты и глубины страниц. Для сравнения языков используйте одинаковые параметры, сохраняйте сырые ответы и показывайте погрешность, а не только красивый топ. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.

Проверьте границу Сравните text Python стажёр и Python junior при одинаковых area и per_page. Объясните, почему списки навыков отличаются. Меняйте одно условие за прогон, чтобы видеть причину.

Проверяем проект и добавляем свою функцию

Добавьте пагинацию на три страницы, CSV с сырыми результатами и столбец share, который показывает долю вакансий с навыком. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.

Проверка своими руками
  1. Сохраните ожидаемый результат: запрос возвращает JSON, детали загружены с паузой, пустые key_skills не ломают подсчёт, а отчёт содержит размер выборки и дату.
  2. Измените правило: добавьте второй город и сравните долю SQL, Git и Docker. Сначала предскажите итог.
  3. Передайте граничное значение и убедитесь, что приложение не падает.
  4. Верните корректные данные и объясните роли трёх основных частей.
Готово, если выполняются все пункты
  • ответ содержит items и found
  • карточка содержит key_skills или пустой список
  • один навык не раздваивается из-за регистра
  • результат можно воспроизвести

После изменения повторите основной и ошибочный сценарии, чтобы новое поведение не сломало исходный результат. Полезная правка проходит от нового ввода до видимого результата.

Четыре контрольные точки HeadHunter API
Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.

Что запомнить и куда двигаться дальше

Не превращайте отчёт в обещание трудоустройства. Это снимок выбранной выдачи, который помогает выбрать следующую учебную тему и проверить гипотезу. Для закрепления откройте в статье про pandas и CSV, в публикации проекта на GitHub и в сайте-портфолио разработчика.

Как изучить тему в Кодике

Сначала разберите формат входных данных и одну функцию, затем подключайте внешний сервис или интерфейс. Сначала восстановите главную функцию и проверьте её на трёх значениях.

ШагЧто разобратьМини-проверка
1. ОсноваСловари, циклы, Counter и функции PythonОбъясните вход и выход функции.
2. ИнструментHTTP GET, параметры, заголовки и пагинацию hh.ruПовторите команду по памяти.
3. ПроектЗагрузку деталей и нормализацию навыковПроверьте два сценария.
4. РефакторингCSV, доли, сравнение регионов и ограничения выборкиРазделите ввод, логику и вывод.

Закрепите проект, восстановив ключевую функцию по памяти и добавив собственный граничный случай. Базовый синтаксис закрепите через курс Python.

Подсчёт только search items

В короткой карточке нет полного key_skills. Загружайте детали.

Нет User-Agent

Запрос не соответствует требованиям API. Укажите приложение и контакт.

20 вакансий названы рынком

Выборка мала и зависит от запроса. Показывайте объём и дату.

Навыки без нормализации

Python и python считаются разными. Используйте strip и lower.

Сверяйтесь с первичной документацией. Команды и ограничения примера проверены по официальной OpenAPI-документации HeadHunter. Если версия инструмента изменилась, официальный источник важнее старого скриншота.

Что получится в итоге

Готовый результат проекта: HeadHunter API на Python: собираем вакансии и считаем самые частые навыки
Финальный экран показывает результат, состояние операции и понятное сообщение об ошибке без раскрытия секретов.

Короткие ответы
Почему нужен второй запрос для каждой вакансии?

Поле key_skills находится в полной карточке, а не в кратком результате поиска.

Что обязательно указывать рядом с топом?

Формулировку запроса, регион, дату и размер выборки.

Что проверять первым, если HeadHunter API не запускается?

Версию среды, текущую папку, команду запуска и первую строку ошибки.

Как понять, что проект HeadHunter API работает?

Проверьте основной сценарий, неверный ввод, повторный запуск и один граничный случай.

Можно ли начать с готового кода?

Да. Добейтесь результата, измените одно правило и восстановите ключевую функцию без копирования.

Сделайте один осознанный шаг дальше

Выберите одно улучшение и проведите его от ввода до результата.

Если не хватает основы, перейдите курс Python, затем восстановите ключевую функцию без подсказки.