API (Документация)



Введение


API - что это и зачем нужно?


API это английская аббревиатура, которая расшифровывается как Application Programming Interface — «Интерфейс Программирования Приложений». Обычно API представляет из себя набор удобных функций, позволяющих получить доступ к какому-либо сервису и запросить у него данные.

API для infohound.ru — это скрипт, который принимает запросы (по методам GET, POST) и отдаёт не обычный HTML для браузеров, а результат запроса в определённом формате (JSON). Предназначен он не пользователям, а скрипту со стороннего сайта/сервиса/программы, который посылает эти GET/POST запросы, получает результат и как-то использует данные. Посылает он запросы естественно не просто так, а чтобы выполнить определённое действие (напр. как действия которые выполняют пользователи сайта через браузер).

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

Так, например, Вы можете разработать свое собственное приложение для infohound.ru и управлять своими запросами вообще не посещая наш сайт. На самом деле API предоставляет огромные возможности и сфера применения API-интерфейсов ничем не ограничена. Появление API-интерфейса у сервиса infohound.ru поможет теперь нашим пользователям решать самые неординарные задачи, интегрируясь с нашим сервисом. А количество функций нашего API-интерфейса со временем будет только расти.

Общая информация

  • Авторизация осуществляется по протоколу OAuth2.0.
  • Все данные доступны только в формате JSON.
  • Базовый URL — https://infohound.ru/api


Терминология


Существует несколько видов HTTP-запросов. Тип запроса указывается в первой строке HTTP-пакета, которая имеет вид:

<ТИП ЗАПРОСА> <ЗАПРАШИВАЕМЫЙ ДОКУМЕНТ> <ВЕРСИЯ HTTP>

Например:

GET /api/check HTTP/1.1

GET-запрос


GET-запрос — это самый распространенный вид HTTP-запроса. При помощи него происходит запрос браузером любого файла веб-сервера. HTTP-запрос типа GET состоит только из HTTP-заголовков, тело у него отсутствует .

При помощи GET-запроса можно передать веб-серверу параметры — некоторую информацию. Например, передача id записи в нашей базе данных, которую вы хотите посмотреть. Рассмотрим механизм передачи параметров с помощью GET-запроса.

В первой строке запроса после ключевого слова GET помещается путь к запрашиваемому документу. Если в пути встречается знак вопроса, то принято считать, что в этом месте путь заканчивается, а за ним начинаются GET-параметры этого запроса:

GET https://infohound.ru/api/v1/request/view?параметры HTTP/1.1

GET-параметр имеет формат имя_параметра=значение_параметра, сами параметры разделяются знаком &. Пример GET-запроса:

GET https://infohound.ru/api/v1/request/view?id=1 HTTP/1.1

GET-параметры можно вручную дописать в браузере в конце запрашиваемого URL в адресной строке.

Например: https://infohound.ru/api/v1/request/view?id=1

Основным преимуществом GET-параметров является их размещение непосредственно в URL.


POST-запрос


Если необходимо передать на веб-сервер большой объем данных, например, текст в формате JSON, используют POST-запрос. В этом типе запроса параметры помещаются в тело HTTP-запроса, а размер передаваемых данных в байтах указывается в заголовке content-length. Если вы передаёте текст в формате JSON, то необходимо указать еще один заголовок content-type: application/json

POST https://infohound.ru/api/v1/request/create HTTP/1.1
    <Различные заголовки>
    content-length: 21
    content-type: application/json
    <Различные заголовки>

    {"last_name":"Путин"}

Таким образом, в URL передаваемые параметры не видны. Простым способом сформировать POST-запрос не получится. Они генерируются с помощью HTML-форм, или в специальных приложениях.


Использование API


Получение кода авторизации


Процесс регистрации приложения

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

https://infohound.ru/oauth2/app
для работы с приложениями.

При создании приложения Вам необходимо придумать название приложения, client_secret (секретное слово, необходимое для получения access_token) и указать redirect_uri (адрес для переадресации, куда будет передан код авторизации, необходимый для получения access_token). client_id вам будет присвоен автоматически.

После регистрации приложения необходимо перейти по адресу:

https://infohound.ru/oauth2/auth
    

Обязательные параметры:

  • response_type=code — указание на способ получение авторизации, используя authorization code;
  • client_id={client_id} <string> — идентификатор, присвоенный вашему приложению при создании;
  • redirect_uri={redirect_uri} <string> — url для перенаправления пользователя после авторизации.

Необязательные параметры:

  • state={state} <string> — любая строка. В случае указания, будет включен в ответный редирект. Это позволяет исключить возможность взлома путём подделки межсайтовых запросов. Подробнее об этом: RFC 6749. Section 10.12

Правила формирования специального redirect_uri

К примеру, если в настройках сохранен http://www.example.ru, то разрешено указывать:

  • http://www.example.ru/api - поддомен;
  • http://www.example.ru/api/sub/path — уточнение пути;
  • http://www.example.ru/api?lang=RU — дополнительный параметр;
  • http://www.example.ru/api/sub/path?lang=RU — всё вместе.

Запрещено:

  • http://example.ru/ — без www (в случае если в настройках www указан);
  • https://www.example.ru/api — различные протоколы;
  • http://www.site.ru/ — другой путь;
  • http://example.ru:80/api — указание изначально отсутствующего порта;




Получение access и refresh токенов


После получения authorization_code приложению необходимо сделать POST или GET запрос на

https://infohound.ru/oauth2/auth/token
для обмена полученного authorization_code на access_token.

Обязательные параметры:

  • grant_type=authorization_code - тип авторизации;
  • client_id={client_id} <string> - идентефикатор вашего приложения;
  • client_secret={client_secret} <string> - ваше секретное слово, указанное при создании приложения;
  • code={authorization_code} <string> - код авторизации, полученный вами;
  • redirect_uri={redirect_uri} <string> - адрес, указанный вами при получении кода авторизации, как параметр, а не тот, который Вы указывали в настройках приложения.

В ответе вернётся JSON:

{
      "access_token": "{access_token}",
      "expires_in ": 1209600,
      "token_type": "bearer",
      "scope": "scope",
      "refresh_token": "{refresh_token}",
    }

где:

  • access_token - ваш access_token;
  • expires_in - время его жизни в секундах;
  • token_type - тип access_token;
  • scope - права доступа;
  • refresh_token - ваш refresh_token, необходимый для обновления пары access и refresh токенов.

authorization_code имеет довольно короткий срок жизни, при его истечении необходимо запросить новый.

Если обмен authorization_code произвести не удалось, то вернётся ответ с телом:

{
        "name": "...",
        "message": "...",
        "code": "...",
        "type": "..."
    }

где:

  • name название ошибки. Например, invalid_request, если какой либо из обязательных параметров не был передан или неверно указан.
  • message будет содержать дополнительное описание ошибки.



Обновление пары access и refresh токенов


access_token также имеет срок жизни (ключ expires_in, в секундах), при его истечении приложение должно сделать запрос с refresh_token для получения нового.

POST или GET https://infohound.ru/oauth2/auth/token
    grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}
    

Ответ будет идентичен ответу на получения токенов в первый раз:

{
      "access_token": "{access_token}",
      "expires_in ": 1209600,
      "token_type": "bearer",
      "scope": "scope",
      "refresh_token": "{refresh_token}",
    }

где:

  • access_token - ваш access_token;
  • expires_in - время его жизни в секундах;
  • token_type - тип access_token;
  • scope - права доступа;
  • refresh_token - ваш refresh_token, необходимый для обновления пары access и refresh токенов.

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


Список методов


Вспомогательные методы (info)


Метод для проверки access_token (check)


После получения access_token Вы можете проверить его. Для проверки Вам необходимо отправить GET запрос на

https://infohound.ru/api/v1/info/check

Обязательные параметры запроса:

  • access_token <string> - access_token, полученный вами при регистрации приложения по протоколу OAuth2.0

Вам вернётся ответ - строка вида

    It works!
    

Возможные ошибки:

Вы передали неправильный access_token:

    
    {
        "name": "invalid_grant",
        "message": "The access token provided is invalid.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    
    

У переданного access_token истёк срок жизни:

    
    {
        "name": "invalid_grant",
        "message": "The access token provided has expired.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    
    

В таком случае необходимо обновить access_token. Как это сделать, описано здесь


Методы для работы с запросами (request)


Создать запрос на поиск (create)


Одновременно можно создать не более 100 запросов.

Для создания запросов вам необходимо послать POST запрос с телом запроса в формате JSON на

https://infohound.ru/api/v1/request/create

Тело запроса должено иметь следующий вид:

    {
        "уникальный id массива данных запроса":{
                                                    /*Массив данных запроса*/
                                                 }
    }
    

Обязательные заголовки запроса:

  • content-type: application/json

Обязательные параметры запроса:

  • access_token <string> - access_token, полученный вами при регистрации приложения по протоколу OAuth2.0

Обязательные поля массива данных:

  • last_name <string> - фамилия (максимальная длина 255 символов)
  • first_name <string> - имя (максимальная длина 255 символов)
  • middle_name <string> - отчество (максимальная длина 255 символов)
  • birthday <date> - день рождения (формат строго yyyy-mm-dd)
  • living_city <string> - город проживания (максимальная длина 255 символов)

Необязательные поля массива данных:

  • birthday_city <string> - город рождения (максимальная длина 255 символов)
  • comment <string> - любой Ваш комментарий (максимальная длина 255 символов). Например id клиента в Вашей базе данных.


Если Вы передадите более одного массива данных, например


    {
        "0":{
                "last_name":"Путин",
                "first_name":"Владимир",
                "middle_name":"Владимирович",
                "birthday":"1952-10-02",
                "living_city":"Москва",
                "birthday_city":"Ленинград",
                "comment":"Ваш комментарий"
             },
        "1":{
                "last_name":"Медведев",
                "first_name":"Дмитрий",
                "middle_name":"Анатольевич",
                "birthday":"1965-09-14",
                "living_city":"Москва",
                "birthday_city":"Ленинград",
                "comment":"Ваш комментарий"
             },
        "3":{
                "last_name":"Ельцин",
                "first_name":"Борис",
                "middle_name":"Николаевич",
                "birthday":"1931-02-01",
                "living_city":"Москва",
                "birthday_city":"Бутка",
                "comment":"Ваш комментарий"
             }
    }
    

Вам вернётся ответ в JSON формате вида

    
    {
        "status":"OK",
        "Added":
            [
                {"id":"1","comment":"Ваш комментарий"},
                {"id":"2","comment":"Ваш комментарий"},
                {"id":"3","comment":"Ваш комментарий"}
            ]
    }
    
    

где id - идентефикатор добавленного запроса в нашей базе данных, comment - комментарий, который вы указали в запросе при его создании.

Если же Вы передали один массив данных, например

    
    {
        "0":{
                "last_name":"Путин",
                "first_name":"Владимир",
                "middle_name":"Владимирович",
                "birthday":"1952-10-02",
                "living_city":"Москва",
                "birthday_city":"Ленинград",
                "comment":"Ваш комментарий"
             }
    }
    

вам вернётся найденная информация по данному запросу в формате JSON (посмотреть формат)


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


    {"0":{"last_name":"Путин","first_name":"Владимир","middle_name":"Владимирович","birthday":"1952-10-02","living_city":"Москва","birthday_city":"Ленинград","comment":"Ваш комментарий"},"1":{"last_name":"Медведев","first_name":"Дмитрий","middle_name":"Анатольевич","birthday":"1965-09-14","living_city":"Москва","birthday_city":"Ленинград","comment":"Ваш комментарий"},"3":{"last_name":"Ельцин","first_name":"Борис","middle_name":"Николаевич","birthday":"1931-02-01","living_city":"Москва","birthday_city":"Бутка","comment":"Ваш комментарий"}}
    

Возможные ошибки:

Вы отправили пустое тело запроса:


    { "Error":"empty request" }
    

Вы пытаетесь добавить более 100 запросов за раз:


    { "Error":"exceeding limit of requests (Max: 100)" }
    

Вы не указали один или несколько обязательных полей тела запроса:


    { "Error":"bad request: there are no required fields" }
    

Вы передали неправильный access_token:


    {
        "name": "invalid_grant",
        "message": "The access token provided is invalid.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

У переданного access_token истёк срок жизни:


    {
        "name": "invalid_grant",
        "message": "The access token provided has expired.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

В таком случае необходимо обновить access_token. Как это сделать, описано здесь





Вывести список запросов (list)


Для просмотра ваших запросов вам необходимо послать POST или GET запрос на

https://infohound.ru/api/v1/request/list

Обязательные параметры запроса:

Необязательные параметры запроса:

В случае успешного выполнения запроса вам вернётся ответ в JSON формате вида


    {
        "id":1,
        "last_name":"Путин",
        "first_name":"Владимир",
        "middle_name":"Владимирович",
        "living_city":"Москва",
        "birthday_city":"Ленинград",
        "birthday":"1952-10-02",
        "created_at": "2016-01-01 00:00:00",
        "updated_at": "2016-04-27 00:00:00",
        "comment":"Ваш комментарий"
    }
    

Возможные ошибки:

Параметр limit не число:


    { "Error":"bad request: limit is not numeric" }
    

Параметр offset не число:


    { "Error":"bad request: offset is not numeric" }
    

Список запросов пуст:


    { "Error":"list is empty" }
    

Вы передали неправильный access_token:


    {
        "name": "invalid_grant",
        "message": "The access token provided is invalid.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

У переданного access_token истёк срок жизни:


    {
        "name": "invalid_grant",
        "message": "The access token provided has expired.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

В таком случае необходимо обновить access_token. Как это сделать, описано здесь




Удалить запрос (delete)


Для удаления запроса вам необходимо послать POST или GET запрос с телом запроса на

https://infohound.ru/api/v1/request/delete

Обязательные параметры запроса:


В случае успешного выполнения запроса вам вернётся ответ в JSON формате вида


    { "status": "OK" }
    

Возможные ошибки:

Отсутствует параметр id (или не число):


    { "Error":"bad request: invalid id" }
    

Запрос с таким id не существует или удалён:


    { "Error":"request not found." }
    

Вы передали неправильный access_token:


    {
        "name": "invalid_grant",
        "message": "The access token provided is invalid.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

У переданного access_token истёк срок жизни:


    {
        "name": "invalid_grant",
        "message": "The access token provided has expired.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

В таком случае необходимо обновить access_token. Как это сделать, описано здесь




Изменить запрос (update)


Для обновления запроса Вам необходимо послать POST запрос с телом запроса в формате JSON на

https://infohound.ru/api/v1/request/update


Тело запроса должено иметь следующий вид:


    {
        "id":1,
        "last_name":"Путин",
        "first_name":"Владимир",
        "middle_name":"Владимирович",
        "birthday":"1952-10-02",
        "living_city":"Москва",
        "birthday_city":"Ленинград",
        "comment":"Ваш комментарий"
    }
    

Обязательные заголовки запроса:

Обязательные параметры запроса:

Обязательные поля тела запроса:


Необязательные поля тела запроса:

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


    {"id":1,"last_name":"Путин","first_name":"Владимир","middle_name":"Владимирович""birthday":"1952-10-02","living_city":"Москва","birthday_city":"Ленинград","comment":"Ваш комментарий"}
    

В случае успешного обновления вам вернётся ответ в JSON формате вида


    { "status":"OK" }
    

Возможные ошибки:

Отсутствует параметр id (или не число):


    { "Error":"bad request: invalid id" }
    

Запрос с таким id не существует или удалён:


    { "Error":"request not found." }
    

Вы передали неправильный access_token:


    {
        "name": "invalid_grant",
        "message": "The access token provided is invalid.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

У переданного access_token истёк срок жизни:


    {
        "name": "invalid_grant"
        "message": "The access token provided has expired."
        "code": 0
        "type": "conquer\oauth2\Exception"
    }
    

В таком случае необходимо обновить access_token. Как это сделать, описано здесь




Обновить запрос (refresh)


Обновить запрос - заново произвести поиск по тем же данным. Для обновления запроса вам необходимо послать POST или GET запрос на

https://infohound.ru/api/v1/request/refresh

Обязательные параметры запроса:

В случае успешного обновления вам вернётся ответ в JSON формате с полученными данными.
Его структура полностью совпедает с ответом при выполнении метода create.


Возможные ошибки:

Отсутствует параметр id (или не число):


    { "Error":"bad request: invalid id" }
    

Запрос с таким id не существует или удалён:


    { "Error":"request not found." }
    

Вы передали неправильный access_token:


    {
        "name": "invalid_grant",
        "message": "The access token provided is invalid.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

У переданного access_token истёк срок жизни:


    {
        "name": "invalid_grant"
        "message": "The access token provided has expired."
        "code": 0
        "type": "conquer\oauth2\Exception"
    }
    

В таком случае необходимо обновить access_token. Как это сделать, описано здесь

Получить данные по запросу (get)


Для проверки запроса вам необходимо послать POST или GET запрос на

https://infohound.ru/api/v1/request/get

Обязательные параметры запроса:


В случае, если отправлена пара access_token и id, проверка на готовность будет производится одного запроса с id нашей внутренней базы.

Вам вернётся ответ в JSON формате


    {  
    "vkontakte":[  
       {
          "uid":"id пользователя",                 <int>
          "last_name":"Фамилия пользователя",      <string>
          "city":{ 
             "title":"Название города"             <string>
          },             
          "domain":"Домен",                        <string>
          "photo":"Ссылка на аватар пользователя", <string>
          "last_seen":{
             "time":"Временная метка последнего сеанса", <Unix time stamp>
             "platform":"Тип платформы", <1 - 'Мобильная версия сайта или неопознанное мобильное приложение',
                                          2 - 'Официальное приложение для iPhone',
                                          3 - 'Официальное приложение для iPad',
                                          4 - 'Официальное приложение для Android',
                                          5 - 'Официальное приложение для Windows Phone',
                                          6 - 'Официальное приложение для Windows 8',
                                          7 - 'Полная версия сайта или неопознанное приложени'>
          },
          "wall_comments":"Можно ли оставлять комментарии на стене",      <bool>
          "can_post":"Можно ли писать пользователю на стене",             <bool>
          "can_see_all_posts":"Можно ли смотреть все фото",               <bool>
          "can_write_private_message":"Можно ли писать личные сообщения", <bool>
          "can_send_friend_request":"Можно ли отправить заявку в друзья", <bool>
          "website":"Сайт",                      <string>
          "followers_count":"Число подписчиков", <int>
          "status":"Статус",                     <string>
          "verified":"Подтверждена ли страница", <bool>
          "universities":[
             {
                "name":"Название университета",           <string>
                "faculty_name":"Название факультета",     <string>
                "chair_name":"Название специальности",    <string>
                "graduation":"Год окончания университета" <int>
             }
          ],
          "schools":[
             {
                "name":"Название школы",              <string>
                "year_from":"Год начала обучения",    <int>
                "year_to":"Год окончания обучения",   <int>
                "class":"Название класса",            <string>
                "speciality":"Название специальности" <string>
             }
          ],
          "groups":{
             "count":"Количество групп", <int>
             "items":[
                {
                   "id":"id группы",                                 <int>
                   "name":"Название",                                <string>
                   "screen_name":"Псевдоним id",                     <string>
                   "is_closed":"Закрыта ли группа",                  <bool>
                   "is_admin":"Пользователь - администратор группы", <bool>
                   "type":"Тип",                                     <group - группа
                                                                      page - публичная страница
                                                                      event - мероприятие>
                   "deactivated":"banned",                           <banned  - группа заблокирована
                                                                      deleted - группа удалена> 
                   "photo_50":"Ссылка на фото группы",               <string>
                   "photo_100":"Ссылка на фото группы",              <string>
                   "photo_200":"Ссылка на фото группы"               <string>
                }
             ]
          },
          "friends":{
             "count":"Количество друзей", <int>
             "items":[
                {
                   "id":"id друга",             <int>
                   "first_name":"Имя",          <string>
                   "last_name":"Фамилия",       <string>
                   "sex":"Пол",                 <1 - женский, 
                                                 2 - мужской, 
                                                 0 - без указания пола>
                   "city":{
                      "title":"Название города" <string>
                   },
                   "country":{
                      "title":"Название страны" <string>
                   },
                   "relation":"Тип отношений", <1 - не женат/не замужем 
                                                2 - есть друг/есть подруга 
                                                3 - помолвлен/помолвлена 
                                                4 - женат/замужем 
                                                5 - всё сложно 
                                                6 - в активном поиске 
                                                7 - влюблён/влюблена>
                   "relation_partner":{
                     "id":"id Партнёра",            <int>
                     "first_name":"Имя партнёра",   <string>
                     "last_name":"Фамилия партнёра" <string>
                   },
                   "universities":[
                      {
                         "name":"Название университета",       <string>
                         "faculty_name":"Название факультета", <string>
                         "chair_name":"Название кафедры",      <string>
                         "graduation":"Год окончания",         <int>
                         "education_form":"Форма обучения",    <string>
                         "education_status":"Статус обучения"  <string>
                      }
                   ],
                   "schools":[
                      {  
                         "name":"Название школы",                            <string>
                         "year_from":"Год начала обучения",                  <int>
                         "year_to":"Год предполагаемого окончания обучения", <int>
                         "year_graduated":"Год окончания обучения",          <int>
                         "class":"Название класса"                           <string>
                      }
                   ],
                   "online":"Онлайн или оффлайн в текущий момент",              <bool>
                   "set_phone":"Указан хотя бы один телефон",                   <bool>
                   "equal_last_name":"Однофамилец пользователя",                <bool>
                   "equal_city":"Из одного города с пользователем",             <bool>
                   "equal_university":"Из одного университета с пользователем", <bool>
                   "equal_school":"Из одной школы с пользователем"              <bool>
                 }
                ]
             },
             "interests":"Интересы",             <string>
             "music":"Любимая музыка",           <string>
             "tv":"Любимые телешоу",             <string>
             "books":"Любимые книги",            <string>
             "games":"Любимые игры",             <string>
             "mobile_phone":"Мобильный телефон", <string>
             "home_phone":"Домашний телефон",    <string>
             "photos":{
                "count":"Количество фото",       <int>
                "items":[
                   {
                      "photo_130":"Ссылка на фото размера 130px",                     <string>
                      "photo_max":"Ссылка на фото максимального размера из имеющихся" <string>
                   }
                 ]
                }
             ],
             "career":[
                {
                   "company":"Место работы",   <string>
                   "from":"Год начала работы", <int>
                   "position":"Должность"      <string>
                }
             ],
             "relatives":[
                {
                   "id":"id родственника",     <int>
                   "type":"тип родственника"   <grandchild - внук, 
                                                grandparent - бабушка/дедушка, 
                                                child - ребёнок, 
                                                sibling - брат, 
                                                parent - родитель>
                }
             ],
             "relation_partner":[
                {  
                   "id":"id партнера",            <int>
                   "first_name":"Имя партнёра",   <string>
                   "last_name":"Фамилия партнёра" <string>
                }
             ]
          }
       ],
       "odnoklassniki":[
          {  
             "uid":"id пользователя",                                      <string>
             "current_status":"Статус",                                    <string>
             "allows_anonym_access":"Возможен ли доступ без авторизации",  <bool>
             "registered_date":"Дата регистрации формата Y-m-d H:i:s",     <string>
             "private":"Приватный или нет",                                <bool>
             "has_service_invisible":"",                                   <bool>
             "premium":"Премиум аккаунт или нет"                           <bool>
          }
       ],
       "headhunter":[
          {
             "vid":"id объявления",                <string>
             "title":"Заголовок объявления",       <string>
             "amount":"Желаемая заработная плата", <string>
             "currency":"Валюта",                  <string>
             "experience":[
                {
                   "industries":[
                      {
                         "id":"id",                      <string>
                         "name":"Категория деятельности" <string>
                      }
                   ],
                   "start":"Дата начала работы в формате Y-m-d",  <string>
                   "position":"Должность",                        <string>
                   "end":"Дата окончания работы в формате Y-m-d", <string>
                   "area":"Местоположение фирмы",                 <string>
                   "company_url":"Адрес фирмы",                   <string>
                   "industry":"Тип деятельности предприятия",     <string>
                   "company":"Название фирмы"                     <string>
                }
             ],
             "total_experience":"Суммарный опыт работы в месяцах", <string>
             "education":{
                "primary":[
                    {
                        "organization_id":"id организации",     <string>
                        "name_id":"id имени",                   <string>
                        "name":"Название учебного заведения",   <string>
                        "year":"Год окончания",                 <string>
                        "organization":"Название организации",  <string>
                        "result_id":"",                         <string>
                        "result":""                             <string>
                    }
                ]
            },        
             "created_at":"Дата создания объявления в формате Y-m-d H:i:s",  <string>
             "updated_at":"Дата изменения объявления в формате Y-m-d H:i:s"  <string>
          }
       ],
       "superjob":{
            "last_profession":" Последняя профессия", <string>
            "payment":"Сумма оклада",                 <int>
            "currency":"Валюта",                      <string>
            "metro":[
               {
                  "id":"id станции",                  <int>
                  "title":"Название станции",         <string>
                  "id_metro_line":"id ветки"          <int>
               }
            ],
            "address":"Адрес соискателя",             <string>
            "draft":"Проектная работа",               <bool>
            "agreement":"Оклад по договоренности",    <bool>
            "type_of_work":{
                "id":"id",              <6 — полный день
                                         10 — неполный день
                                         12 — сменный график
                                         13 — частичная занятость
                                         7 — временная работа
                                         9 — вахтовым методом>
                "title":"Тип занятости"  <string>
            },
            "place_of_work":{
                "id":"id",             <1 — на территории работодателя
                                        2 — на дому
                                        3 — разъездного характера>
                "title":"Место работы"  <string>
            },
            "education":{
                "id":"id",            <2 — высшее
                                       3 — неполное высшее
                                       4 — средне-специальное
                                       5 — среднее
                                       6 — учащийся>
                "title":"Образование"  <string>
            },
            "children":{
                "id":"id",              <0 — не имеет значения
                                         2 — нет
                                         3 — есть>
                "title":"Наличие детей"  <string>
            },
            "business_trip":{
                "id":"id",                           <0 — не имеет значения
                                                      1 — не готов
                                                      2 — готов>
                "title":"Готовность к командировкам" <string>
            },
            "maritalstatus":{
                "id":"id",                   <2 — состою в браке,
                                              3 — не состою в браке>
                "title":"Семейное положение"  <string>
            },
            "languages":[
                [
                    {
                        "id":"id",               <int>
                        "title":"Название языка" <string>
                    },
                    {
                        "id":"id",                        <0 — не имеет значения
                                                           3 — базовый
                                                           5 — технический
                                                           7 — разговорный
                                                           9 — свободное владение>
                        "title":"Уровень владения языком" <string>
                    }
                ]
            ],
            "driving_license":"Категория водительских прав", <string>
            "catalogues":[
                {
                    "id":"id каталога",<int>
                    "title":"Название каталога категорий и отраслей вакансии",<string>
                    "key":"Ключ",                       <int>
                    "positions":[
                        {
                            "id":"id отрасли",          <int>
                            "title":"Название отрасли", <string>
                            "key":"Ключ отрасли"        <int>
                        }
                    ]
                }
            ],
            "town":{
                "id":"id города",                                <int>
                "title":"Название",                              <string>
                "declension":"Предложный падеж названия города", <string>
                "genitive":"Родительный падеж названия города"   <string>
            },
            "region":{
                "id":"id региона",          <int>
                "title":"Центральный округ" <string>
            },
            "experience_text":"Опыт работы словами",          <string>
            "experience_month_count":"Опыт работы в месяцах", <int>
            "work_history":[
                {
                    "town":{
                        "id":"id города",                                <int>
                        "title":"Название",                              <string>
                        "declension":"Предложный падеж названия города", <string>
                        "genitive":"Родительный падеж названия города"   <string>
                    },
                    "townName":"Название города",  <string>
                    "name":"Название фирмы",       <string>
                    "profession":"Профессия",      <string>
                    "work":"Обязанности",          <string>
                    "type":{
                        "id":"id",                <6 — полный день
                                                   10 — неполный день
                                                   12 — сменный график
                                                   13 — частичная занятость
                                                   7 — временная работа
                                                   9 — вахтовым методом>
                        "title":"Тип занятости"    <string>
                    },
                    "monthbeg":"Месяц начала работы",    <int>
                    "monthend":"Месяц окончания работы", <int>
                    "yearbeg":"Год начала работы",       <int>
                    "yearend":"Год окончания работы"     <int>
                }
            ],
            "base_education_history":[
                {
                    "institute":{
                        "id":"id учебного заведения",         <int>
                        "title":"Название учебного заведения" <string>
                    },
                    "town":{
                        "id":"id города",                     <int>
                        "title":"Название"                    <string>
                    },
                    "faculty":"Название факультета",          <string>
                    "profession":"Профессия",                 <string>
                    "education_type":{
                        "id":"id",               <2 — Высшее
                                                  3 — Неполное высшее
                                                  4 — Среднее специальное
                                                  5 — Среднее
                                                  6 — Учащийся школы
                                                  7 — Бакалавр
                                                  8 — Магистр
                                                  9 — Кандидат наук
                                                  10 — Доктор наук>
                        "title":"Тип образования" <string>
                    },
                    "education_form":{
                        "id":"id",                  <10 — Дневная/Очная
                                                     20 — Вечерняя
                                                     30 — Очно-заочная
                                                     40 — Заочная
                                                     50 — Экстернат
                                                     60 — Дистанционная>
                        "title":"Форма образования"  <string>
                    },
                    "yearend":"Год окончания" <int>
                }
            ],
            "education_history":[
                {
                    "institute":"Название учебного заведения",           <string>
                    "town":{
                        "id":"id города",                                <int>
                        "title":"Название",                              <string>
                        "declension":"Предложный падеж названия города", <string>
                        "genitive":"Родительный падеж названия города"   <string>
                    },
                    "townName":"Название города",                        <string>
                    "name":"Название курсов или тренингов",              <string>
                    "yearend":"Год окончания"                            <string>
                }
            ],
            "contacts_bought":"Куплены ли (или доступны согласно тарифу) контакты резюме", <bool>
            "resume_price":"Стоимость резюме",                             <string>
            "phones":[
                {
                    "phone":"Номер телефона (в формате +7 (999) 999-99-99)", <string>
                    "call_from":"Звонить с (в формате 19:00)",               <string>
                    "call_to":"Звонить до (в формате 19:00)"                 <string>
                }
            ]
            "email":"E-mail",                                             <string>
            "other_contacts":"Дополнительные контакты",                   <string>
            "recommendations":"Рекомендации",                             <string>
            "social_links":[
               {
                  "id":"id социальной сети",                              <int>
                  "title":"Название социальной сети",                     <string>
                  "link":"Ссылка"                                         <string>
               }
            ],
            "received_resume_info":{
                "status":"Статус",                                        <string>
                "id_user":"id пользователя",                              <int>
                "new_event":"Новые события",                              <string>
                "events":"События"                                        <array>
            },
            "link":"Прямая ссылка на резюме",                             <string>
            "achievements":"Достижения",                                  <string>
            "date_published":"Дата публикации",                           <timestamp>
            "date_last_modified":"Дата последнего редактирования резюме", <timestamp>
            "profession":"Название желаемой должности",                   <string>
            "is_archive":"В архиве",                                      <bool>
            "id_user":"id пользователя",                                  <string>
            "portfolio":"Портфолио",                                      <string>
       },
       "mailru":{  
            "_id":"id пользователя",              <int>
            "first_name":"Имя",                   <string>
            "last_name":"Фамилия",                <string>
            "region":"Регион",                    <string>
            "city":"Город",                       <string>
            "status_text":"Статус пользователя",  <string>
            "following":"Количество подписчиков", <int>
            "video_count":"Количество видео",     <int>
            "friends_count":"Количество друзей",  <int>
            "app_count":"Количество приложений",  <int>
            "vip":"Является ли страница Vip",     <bool>
            "email":"E-mail"                      <string>
       }
    }
    

В случае, если отправлена пара access_token и comment, проверка на готовность будет производится всех запросов, у которых поле comment совпадает с переданным Вами comment.

Вам вернётся ответ в JSON формате, вида

    {
        id: {/*вся найденная информация, как в первом варианте, если запрос готов, либо сообщение о том, что он не готов*/}
    }
    

Возможные ошибки:

Отсутствуют обязательные параметры (id или comment):


    { "Error":"the request does not set the parameters" }
    

Переданы одновременно и id, и comment:


    { "Error":"parameter must be one" }
    

Запрос с таким id или comment не существует:


    { "Error":"requests not found" }
    

Вы передали неправильный access_token:


    {
        "name": "invalid_grant",
        "message": "The access token provided is invalid.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

У переданного access_token истёк срок жизни:


    {
        "name": "invalid_grant",
        "message": "The access token provided has expired.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

В таком случае необходимо обновить access_token. Как это сделать, описано здесь



Создать запрос по номеру телефона (phone)


Для создания запроса вам необходимо послать POST или GET запрос на

https://infohound.ru/api/v1/request/phone

Обязательные параметры запроса:


Вам вернётся ответ в JSON формате, вида


    {
        
        "avito": [
            {
                "id": "id объявления",
                "phone": "Номер телефона",
                "title": "Заголовок объявления",
                "name": "Имя автора",
                "salary": "Желаемая заработная плата",
                "place_name": "Название населённого пункта",
                "place_lat": "Широта населённого пункта",
                "place_lon": "Долгота населённого пункта",
                "about": "Рассказ о себе",
                "description": "Описание"
            }
        ],
        "irr":[
            {
                "id": "id объявления",
                "title": "Заголовок объявления",
                "phone": "Номер телефона",
                "owner": "Имя автора",
                "owner_addr": "Адрес",
                "price": "Цена",
                "date": "Дата публикации",
                "description": "Описание",
                "description_more": "Подробное описание",
                "uid": "id пользователя",
                "type": "Тип"
            }
        ]
    }
    

Возможные ошибки:

Отсутсвует параметр number:


    { "Error":"bad request: invalid number" }
    

Параметр number указан в неверном формате:


    { "Error":"bad request: the phone number should be in the format 89999999999" }
    

Данные по номеру телефона не найдены:


    { "avito":"not found" }
    
или

    { "irr":"not found" }
    

Вы передали неправильный access_token:


    {
        "name": "invalid_grant",
        "message": "The access token provided is invalid.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

У переданного access_token истёк срок жизни:


    {
        "name": "invalid_grant",
        "message": "The access token provided has expired.",
        "code": 0,
        "type": "conquer\oauth2\Exception"
    }
    

В таком случае необходимо обновить access_token. Как это сделать, описано здесь