HeadHunter API можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. Открытый API hh.ru позволяет искать вакансии по тексту и региону, а затем получать подробную карточку с массивом key_skills. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.
Список вакансий не содержит всех навыков, выборка ограничена и меняется каждый день, поэтому одна страница поиска не является статистикой рынка. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте скрипт, который берёт первые вакансии Python-стажёров в Москве, загружает карточки и печатает десять самых частых навыков. Проверка: запрос возвращает JSON, детали загружены с паузой, пустые key_skills не ломают подсчёт, а отчёт содержит размер выборки и дату.
вызвать GET /vacancies с text, area и per_page. Не расширяйте проект до первого успешного запуска.
карточка содержит key_skills или пустой список. Проверяйте значение, а не отсутствие ошибки.
После успеха добавьте второй город и сравните долю SQL, Git и Docker. Так копирование станет практикой.
Как устроен учебный проект HeadHunter API
Первый запрос получает список вакансий, второй этап загружает детали по URL каждой карточки, Counter считает нормализованные названия навыков. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.
| Этап | Действие | Проверяемый результат |
|---|---|---|
| Поиск | вызвать GET /vacancies с text, area и per_page | ответ содержит items и found |
| Детали | загрузить URL каждой вакансии | карточка содержит key_skills или пустой список |
| Подсчёт | нормализовать названия и обновить Counter | один навык не раздваивается из-за регистра |
| Отчёт | вывести top-10, дату и размер выборки | результат можно воспроизвести |
Контрольные точки: поиск, детали, подсчёт и отчёт. Следующий шаг начинается после совпадения с ожидаемым результатом.

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.
Собираем рабочий пример шаг за шагом
Материал сверялся с официальной документацией 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.
- Повторный запуск даёт тот же предсказуемый результат.
- Пустой ввод получает понятное сообщение вместо падения.
Главная функция принимает явный вход и возвращает результат, который можно проверить отдельно от интерфейса. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.
Что происходит внутри и почему это работает
Search endpoint возвращает краткие карточки и URL деталей. key_skills находятся в полной вакансии, поэтому для точного подсчёта нужен второй ограниченный цикл запросов. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. API просит передавать User-Agent. Не увеличивайте частоту запросов бесконечно и не называйте двадцать вакансий полной картиной рынка.
| Часть | За что отвечает | Что проверить |
|---|---|---|
| Поиск | задаёт запрос, город и страницу | found и items читаются отдельно |
| Детали | добавляют key_skills каждой карточки | ошибка одной вакансии журналируется |
| Counter | считает нормализованные названия | отчёт содержит размер выборки |
Результат зависит от формулировки text, региона, даты и глубины страниц. Для сравнения языков используйте одинаковые параметры, сохраняйте сырые ответы и показывайте погрешность, а не только красивый топ. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.
Проверяем проект и добавляем свою функцию
Добавьте пагинацию на три страницы, CSV с сырыми результатами и столбец share, который показывает долю вакансий с навыком. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.
- Сохраните ожидаемый результат: запрос возвращает JSON, детали загружены с паузой, пустые key_skills не ломают подсчёт, а отчёт содержит размер выборки и дату.
- Измените правило: добавьте второй город и сравните долю SQL, Git и Docker. Сначала предскажите итог.
- Передайте граничное значение и убедитесь, что приложение не падает.
- Верните корректные данные и объясните роли трёх основных частей.
- ответ содержит items и found
- карточка содержит key_skills или пустой список
- один навык не раздваивается из-за регистра
- результат можно воспроизвести
После изменения повторите основной и ошибочный сценарии, чтобы новое поведение не сломало исходный результат. Полезная правка проходит от нового ввода до видимого результата.

Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.
Что запомнить и куда двигаться дальше
Не превращайте отчёт в обещание трудоустройства. Это снимок выбранной выдачи, который помогает выбрать следующую учебную тему и проверить гипотезу. Для закрепления откройте в статье про pandas и CSV, в публикации проекта на GitHub и в сайте-портфолио разработчика.
Как изучить тему в Кодике
Сначала разберите формат входных данных и одну функцию, затем подключайте внешний сервис или интерфейс. Сначала восстановите главную функцию и проверьте её на трёх значениях.
| Шаг | Что разобрать | Мини-проверка |
|---|---|---|
| 1. Основа | Словари, циклы, Counter и функции Python | Объясните вход и выход функции. |
| 2. Инструмент | HTTP GET, параметры, заголовки и пагинацию hh.ru | Повторите команду по памяти. |
| 3. Проект | Загрузку деталей и нормализацию навыков | Проверьте два сценария. |
| 4. Рефакторинг | CSV, доли, сравнение регионов и ограничения выборки | Разделите ввод, логику и вывод. |
Закрепите проект, восстановив ключевую функцию по памяти и добавив собственный граничный случай. Базовый синтаксис закрепите через курс Python.
В короткой карточке нет полного key_skills. Загружайте детали.
Запрос не соответствует требованиям API. Укажите приложение и контакт.
Выборка мала и зависит от запроса. Показывайте объём и дату.
Python и python считаются разными. Используйте strip и lower.
Что получится в итоге

Финальный экран показывает результат, состояние операции и понятное сообщение об ошибке без раскрытия секретов.
Почему нужен второй запрос для каждой вакансии?
Поле key_skills находится в полной карточке, а не в кратком результате поиска.
Что обязательно указывать рядом с топом?
Формулировку запроса, регион, дату и размер выборки.
Что проверять первым, если HeadHunter API не запускается?
Версию среды, текущую папку, команду запуска и первую строку ошибки.
Как понять, что проект HeadHunter API работает?
Проверьте основной сценарий, неверный ввод, повторный запуск и один граничный случай.
Можно ли начать с готового кода?
Да. Добейтесь результата, измените одно правило и восстановите ключевую функцию без копирования.
Выберите одно улучшение и проведите его от ввода до результата.
Если не хватает основы, перейдите курс Python, затем восстановите ключевую функцию без подсказки.