API hh.ru. Быстрый старт

  • Tutorial

Полагаю, некоторые из вас знают, что у hh.ru есть открытый API (мы рассказывали о нем тут и тут), который используем не только мы, но и сторонние разработчики. С его помощью, например, можно очень детально анализировать рынок на больших объемах актуальных данных.

Я задумал серию из двух статей: в этой покажу, как можно быстро и просто начать использовать API, а в следующей сделаю небольшой проект, рекомендующий актуальные вакансии по вашему резюме.

Сначала вкратце о том, что вообще есть в нашем API, где и как его используют.

Возможности API


Чтобы быстро получить представление о возможностях API, обратите внимание, например, на наши мобильные приложения для соискателя (Android, iOS) и работодателя (Android, iOS). Они работают через API.

Например, внешние разработчики могут получить все актуальные и архивные вакансии с зарплатами и остальными деталями. А это почти 400 тыс. живых вакансий и еще черт знает сколько архивных. Желающие проанализировать рынок, поиграться с большим количеством реальных данных — вам сюда.

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

За более детальной информацией обращайтесь к нашей документации.

Как работает API?


Всё взаимодействие происходит про протоколу HTTPS в лучших традициях REST. Получаем что-то — делаем GET-запрос, удаляем — DELETE, создаем — POST, редактируем — PUT. Обмен данными производится в формате JSON. Некоторые операции доступны без авторизации, другие — нет. Авторизованный пользователь может выступать в роли работодателя или соискателя. От этого зависит, какие методы ему доступны. Для авторизации используется протокол OAuth2 (о том, как это сделать, я объясню на пальцах ниже). Работать можно с данными любого из наших сайтов. Детали в разделе «Общая информация» документации.

Начало работы


Для того чтобы начать работать с данными, доступными без авторизации, вам ничего не потребуется. Смотрим в документации, какие методы можно использовать, делаем запрос — получаем данные. Например, если хочется посмотреть вакансии
curl -k -H 'User-Agent: api-test-agent' 'https://api.hh.ru/vacancies'

Следует обратить внимание, что нужно передавать заголовок User-Agent. Без него работать не будет.

Для поиска вакансий можно задавать разные параметры.
Так, например, можно поискать вакансию по ключевому слову Java в Москве у станции метро «Алексеевская»
curl -k -H 'User-Agent: api-test-agent' 'https://api.hh.ru/vacancies?text=java&area=1&metro=6.8'

Значения area и metro можно получить из справочников.

Авторизация


Как уже было сказано, для авторизации используется протокол OAuth2.
Чтобы делать что-то из-под пользователя, для него требуется получить токен и передавать этот токен в заголовке при запросе. Для получения токена для своего пользователя достаточно его сгенерировать в интерфейсе API. Заходим в личный кабинет на https://dev.hh.ru и нажимаем на кнопку «Сгенерировать токен».

Чтобы остальные пользователи могли выполнять действия в вашем приложении, это приложение необходимо сначала завести в личном кабинете. Добавляем приложение, указав redirect URI. На этот адрес пользователь будет автоматически возвращаться после авторизации.

После добавления приложения, ему будут присвоены Client ID и Client Secret.

Как работает авторизация?


В своем приложении вы размещаете ссылку на авторизацию, указывая в ней Client ID приложения, например,
https://hh.ru/oauth/authorize?response_type=code&client_id=LOTHHN3BSET0I7IQNF3N5I0362AE1D14I6M74CAIQ5H49F7MT4PLMTVV7JTOA6QA

Когда пользователь переходит по этой ссылке, для него на нашей стороне генерируется специальный код. И наш сайт перенаправляет пользователя обратно в ваше приложение (по redirect URI, который был указан при регистрации приложения), добавив к адресу вашего приложения параметр, содержащий код. Например:
http://yourapphost/?code=J2CO4TM7PK58NNVFCJSLPMML15IKQERD5CT2L8VGK82Q333ILAKQ28BPURIO1LG8

После этого вы вытаскиваете из этого адреса code и используете его для получения токена, сделав POST-запрос в API, передав code, client_id и client_secret.
curl -k -X POST -H 'User-Agent: api-test-agent' -d 'grant_type=authorization_code&client_id=LOTHHN3BSET0I7IQNF3N5I0362AE1D14I6M74CAIQ5H49F7MT4PLMTVV7JTOA6QA&client_secret=JS33UVG3J6JANNEATPND57BME23BKDCPP2UH1NB0C21HUMNGS5T71AVP6P24E0EI&code=J2CO4TM7PK58NNVFCJSLPMML15IKQERD5CT2L8VGK82Q333ILAKQ28BPURIO1LG8' https://hh.ru/oauth/token

В ответ вы получите json, содержащий токен (поле access_token):
{
  "access_token": "VTEJ4PDD8R4MHEO7LTQM6RLEGJ1O8B1F79TGF45LIDQD11K50HMMBETB47BBCMQ1",
  "token_type": "bearer",
  "expires_in": 1209599,
  "refresh_token": "OARLQNLT6JSMDI88CO5QIP35OOSQUTOO9IQNT20MOMAHE4H8SGPM7LQUAP8EO1G6"
}

Это всё. Далее, выполняя запросы в API с заголовком Authorization: Bearer your_access_token, вы будете выполнять действия из-под пользователя. Чтобы на каждый запрос не выполнять авторизацию, сохраняйте у себя access_token.

Вот, например, запрос для получения списка резюме текущего пользователя:
curl -k -H 'Authorization: Bearer VTEJ4PDD8R4MHEO7LTQM6RLEGJ1O8B1F79TGF45LIDQD11K50HMMBETB21BBCMQ1' -H 'User-Agent: api-test-agent' https://api.hh.ru/resumes/mine

Следует учесть, что у токена есть срок жизни, указанный в поле expires_in, после истечения которого токен надо обновить.

API постоянно растет, в нем реализуется всё больше новых возможностей. Если вам сильно не хватает какого-то функционала, есть пожелания или вы нашли ошибку, то напишите нам в issues на гитхабе.
Метки:
HeadHunter 103,25
HR Digital
Поделиться публикацией
Похожие публикации
Комментарии 16
  • +4
    Если кто на java будет писать, для упрощения работы с OAuth2, порекомендую библиотечку ScribeJava.
    В ней из коробки поддерживается API от hh.ru
    https://github.com/scribejava/scribejava/blob/master/scribejava-apis/src/test/java/com/github/scribejava/apis/examples/HHExample.java
    (собственно она в самом hh.ru и используется для работы со своим же API)
    • 0
      А на apigee.com можно поиграться с вашим API?
      • 0
        Спасибо за статью
        Один момент, откуда берем client_secret?
        • 0
          Генерируется автоматически при создании прижения в личном кабинете на https://dev.hh.ru
          • 0
            Спасибо.
            Правда прошелся по диагонали и понял, что в статье написано было, упустил момент.
        • +1
          Неплохое начало. Буду ждать продолжения.
          • +1
            Ребят, небольшой фидбэк.
            Полгода назад сам разбирался с вашим апи, и затупил на одной простой вещи: не принимался access token.
            Пару часов потратил, пока не понял, что нужно слово Bearer дописать.
            Если у меня подозрение, что не я один такой, так что, пожалуйста, либо в документации обратите на это внимание, либо даже проверку сделайте)
            • 0
              Спасибо за отзыв. В выдаче ошибки будет расширено описание
            • 0
              Почему у вас во всех вакансиях совпадают значения «created_at» и «published_at»?
              • 0
                Так сложилось исторически. Не используйте поле created_at — оно не описано в документации
                • 0
                  Спасибо за ответ. А возможно ли другим способом получить через API реальную дату создания вакансии, а не дату ее последней публикации?
                  • 0
                    Нет, эта информация не возвращается
              • 0
                Насколько я понял, то обновить access_token можно только если есть приложение?
                • 0
                  всё так.
                  • 0
                    а как обновлять если такой не нужен? Ведь только токен нужен если:
                    Если приложение обращается
 только к вашему аккаунту на hh.ru
                    а остальное мне даром и не нужно.
                    • 0
                      токен выданный в личном кабинете в dev.hh.ru действует примерно 2 недели. каждые 2 недели или чаще можно получать новый.

                      если хочется получить «постоянный токен», нужно зарегистрировать приложение, провести авторизацию приложения (можно вручную, хватит curl'а), затем получить пару access token + refresh token, их можно будет по истечению 2-х недель поменять на новую пару access token + refresh token и так далее.

                      ограничение времени жизни access token'а сделано по соображением безопасности.

                Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                Самое читаемое