От первого запроса
до своего исследования.

01. Получите доступ

Откройте «Первый вход», укажите ФИО и группу, установите пароль. В кабинете нажмите «Выпустить ключ». Сохраните ключ в переменной окружения HH_STUDY_TOKEN; повторно посмотреть его целиком нельзя.

Базовый URL: https://milushkoff.ru/hh-api

Authorization: Bearer ВАШ_ЛИЧНЫЙ_КЛЮЧ

Передавайте ключ только в заголовке. Ключи hh.ru и вход на hh.ru студентам не нужны. При перевыпуске вашего ключа предыдущий перестаёт работать сразу.

02. Найдите город и количество вакансий

1. Откройте справочник городов непосредственно на hh.ru ↗. Для этой ссылки личный учебный ключ не нужен.
2. Нажмите Ctrl+F (на Mac — Cmd+F) и найдите название города. У найденного объекта возьмите поле id; не перепутайте город с областью. Москва — 1, Санкт-Петербург — 2. Можно проверить карточку Санкт-Петербурга ↗.
3. В Python-примере укажите area='2'. Остальные запросы исследования выполняйте через учебный портал с личным ключом.

params = {'area': '2', 'text': 'аналитик данных', 'per_page': 1}
# После запроса (полный код ниже):
print(data['found'])       # Все совпадения по условиям поиска
print(len(data['items'])) # Вакансии только на текущей странице

Если найдено 125 вакансий, при per_page=1 вы получите одну карточку, а found будет равно 125. Это условный пример. Для сравнения городов отправьте отдельный запрос для каждого города с одинаковыми остальными фильтрами.

03. Загрузите полное описание

Возьмите items[0].id из поиска и выполните GET /vacancies/ID. Поле description содержит HTML; key_skills — навыки. Некоторые поля, в том числе зарплата, могут быть null. Проверяйте наличие значений перед обработкой.

Ссылка url ведёт на учебный API, а alternate_url — на страницу вакансии hh.ru. В справочнике перечислены все доступные методы; ссылки на остальные API-ресурсы возвращают 404.

04. Работайте со страницами

Сервер выдаёт вакансии порциями — страницами. per_page задаёт размер порции (не больше 100), а page — её номер, начиная с нуля.

found — сколько вакансий найдено; items — карточки этой страницы; pages — число доступных страниц. Если pages=3, запросите страницы 0, 1 и 2.

Ниже показан фрагмент цикла из полного Python-примера. client.get — функция отправки запроса с вашим ключом; её код есть в research.py.

for page in range(20):
    data = client.get('/vacancies', {**params, 'per_page': 100, 'page': page})
    for vacancy in data['items']:
        print(vacancy['id'], vacancy['name'])
    if not data['items'] or page + 1 >= data['pages']:
        break  # Все доступные страницы уже получены

Один поиск позволяет выгрузить не более 2000 вакансий. Если found больше, уточните профессию, город или период: выгрузка первых 2000 не является полной. При объединении поисков удаляйте повторяющиеся ID. Для одного лишь подсчёта достаточно запроса с per_page=1 и поля found.

05. Запустите пример

Оба примера — Python 3.10+, без установки дополнительных библиотек. Скачайте файл, откройте терминал в его папке и запустите его. Ключ вводится скрыто при запуске или берётся из HH_STUDY_TOKEN.

Windows: py -3 first-request.py. macOS/Linux: python3 first-request.py. Для исследования замените имя файла на research.py. Это команды терминала.

Код первого запроса

"""Первый запрос. Python 3.10+, установка дополнительных библиотек не нужна."""
import getpass
import json
import os
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

base = os.getenv('HH_STUDY_BASE', 'https://milushkoff.ru/hh-api').rstrip('/')
# Ключ вводится при запуске, а не сохраняется в файле с кодом.
token = os.getenv('HH_STUDY_TOKEN') or getpass.getpass('Личный API-ключ (ввод скрыт): ')
params = {'area': '2', 'text': 'аналитик данных', 'per_page': 1}
request = Request(base + '/vacancies?' + urlencode(params),
                  headers={'Authorization': 'Bearer ' + token.strip()})
try:
    with urlopen(request, timeout=25) as response:
        data = json.load(response)
        print('HTTP:', response.status)
    print('Всего найдено:', data['found'])
    print('На этой странице:', len(data['items']))
    if data['items']:
        print('Первая вакансия:', data['items'][0]['name'])
    else:
        print('По этим условиям вакансий нет. Попробуйте другой запрос.')
except HTTPError as error:
    print('Ошибка HTTP:', error.code)
    if error.code == 429:
        print('Подождите Retry-After секунд:', error.headers.get('Retry-After', 'см. ответ сервера'))
    elif error.code == 401:
        print('Проверьте личный ключ в кабинете.')
    else:
        print('Посмотрите раздел «Ошибки» в инструкции или сообщите преподавателю.')
except (URLError, TimeoutError):
    print('Нет соединения с учебным API. Проверьте интернет и повторите позже.')

Подробный запуск и описание результатов → · Задание преподавателя и выбор темы →

06. Обрабатывайте ошибки

По умолчанию общий поток к hh.ru — один запрос в секунду. Кеш позволяет студентам пользоваться уже загруженными ответами. X-Cache показывает источник ответа, Age — возраст кеша, X-Request-ID помогает найти запрос в журнале.

Кеш поиска — до 5 минут, описания — до 30 минут, справочников — до суток. Счётчики включают успешные запросы, ошибки и ответы из кеша. Документация и вход в кабинет не расходуют квоту API.