С помощью этого запроса, помимо обычного регистронезависимого поиска по персонам, можно реализовать быстрый AJAX-поиск. Например, пользователь вписывает в строку поиска запрос «Пушкин». И в процессе ввода каждого символа из поискового запроса приложение осуществляет поиск по «пуш», «пушк», «пушки» и т.д., быстро предлагая пользователю подходящих персон.

ID функции

r_search_persons

Кто может вызывать

Любой пользователь
Авторизованное приложение

Принимаемые параметры

q – строка с поисковым запросом. По умолчанию подбор результатов производится по широким критериям поиска (при этом минимальная длина rпоискового запроса – 3 символа).
last – фамилия персоны. Если передан этот параметр то q игнорируется. Поиск по фамилии всегда осуществляется по «start»-соответствию, то есть поиск вернет всех авторов, чья фамилия начинается с поисковой строки. Минимальная длина параметра – 1 символ.
first – имя персоны. Если передан этот параметр то должен быть передан параметр last. Поиск по имени всегда осуществляется по «start»-соответствию, то есть поиск вернет всех авторов, чьё имя начинается с поисковой строки. Минимальная длина параметра – 1 символ.
middle – отчество персоны. Если передан этот параметр то должен быть передан параметр last. Поиск по отчеству всегда осуществляется по «start»-соответствию, то есть поиск вернет всех авторов, чьё отчество начинается с поисковой строки.Минимальная длина параметра – 1 символ.
limit – ограничение на количество возвращаемых персон. Работает аналогично инструкции limit в MySQL и в запросе представлен массивом из двух чисел N,M. Если limit указан­ – возвращается M персон, начиная с персоны N (у первой номер 0). Если limit не задан – значение по умолчанию «0,20»;
type – массив, в котором перечислены типы персон для поиска. Если этот массив не передан в запросе, то поиск осуществляется только по авторам (тип 0).
В массиве может быть указан один или несколько типов:

• 0 – Автор текста;
• 1 – Переводчик;
• 2 – Агент;
• 3 – Художник;
• 4 – Составитель;
• 5 – Пересказчик;
• 6 – Чтец;
• 7 – Исполнитель;
• 8 – Производитель;
• 9 – Редактор;
• 10 – Актер;
• 11 – Режиссер;
• 15 – Продюсер;
• 19 – Композитор;
• 23 – Звукорежиссер;
• 26 – Издатель;
• 27 – Сценарист;
• 28 – Владелец прав;
• 29 – Верстальщик;
• 30 – Адаптация;
• 31 – Диалоги;
• 32 – Концепция;
• 33 – Отзыв;
• 34 – Предисловие;
• 35 – Послесловие;
• 36 – Аккомпаниаторы;
• 37 – Цитаты;
• 38 – Аннотация;
• 39 – Связывается с;
• 40 – Комментатор;
• 41 – Консультант;
• 42 – Корректор;
• 43 – Научный советник;
• 44 – Вероятный автор;
• 45 – Дизайнер;
• 46 – Получатель писем;
• 47 – Спонсор;
• 48 – Фотограф;
• 49 – Прочее;
• 50 – Не определено;
• 51 – Главный редактор;
• 52 – Член редколлегии;
• 53 – Ответственный редактор;
• 54 – Соавтор;
• 55 – Иллюстратор;
• 56 – Дизайнер обложки;
• 57 – Лектор.

top_n_arts – если в ответе у каждой персоны необходимо вывести информацию о самых рейтинговых книгах персоны, то в этом параметре указывается необходимое количество книг. Не может быть больше 10.Например, если значение «3», то в ответе у каждой персоны в узле top_arts будет от 0 до 3-х книг имеющих привязку к текущий персоне.
top_n_genres – если в ответе у каждой персоны необходимо вывести информацию о жанрах, к которым относится большинство книг персоны, то в этом параметре указывается необходимое количество жанров. Не может быть больше 10.Например, если значение «3», то в ответе у каждой персоны в узле top_genres будет от 0 до 3-х жанров.
grammatical_case – если параметр присутствует в запросе и имеет значение «1», то в ответе у каждой персоны дополнительно будет выведена фамилия и полное имя во всех падежах (см. last-rodit..full-predl).
descr – если параметр присутствует в запросе и имеет значение «1», то в ответе к найденным персонам будут добавлены описания (см. description_html).

Возвращаемые значения

persons* – массив, содержащий информацию обо всех найденных персонах. Каждая персона представлена следующими элементами:

• id* – ID персоны;
• match_weight* – степень релевантности найденной персоны (значение от 0 до 100, где 100 – максимально релевантно; 0 – наименее релевантно). Учитывает как степень совпадения поискового термина с запросом, так и популярность персоны.
• type – тип персоны (перечень типов см. type в запросе).
• last_update* – время последних изменений по данной персоне в формате «ГГГГ-ММ-ДД ЧЧ:ММ:СС»;
• full_name* – полное имя персоны (Сергей Лукъяненко);
• first_name ­– имя персоны (Сергей);
• last_name – фамилия персоны (Лукъяненко);

• middle_name – отчество персоны (Васильевич). Обратите внимание, что в полном имени отчество может отсутствовать;

  Если в запросе был передан дополнительный параметр grammatical_case=1, то в ответе будут следующие значения: last-rodit – фамилия персоны (родительный падеж); last-dateln – фамилия персоны (дательный падеж); last-vinit – фамилия персоны (винительный падеж); last-tvorit – фамилия персоны (творительный падеж); last-predl – фамилия персоны (предложный падеж); full-rodit – полное название персоны (родительный падеж); full-dateln – полное название персоны (дательный падеж); full-vinit – полное название персоны (винительный падеж); full-tvorit – полное название персоны (творительный падеж); full-predl – полное название персоны (предложный падеж);

• arts_n* ­– количество книг, имеющих привязку к текущий персоне.
• reviews_n – общее количество отзывов (рецензий), оставленных по персоне и одобренных модераторами;
• lvl* – экспертный рейтинг персоны (целое значение от 1 до 5). Отражает ценность персоны с т.з. продаж: 1 – «мусорный» автор, а 5 – автор бестселлеров;
• img – URL до фотографии персоны (может быть полным, с доменом, либо относительным);
• description_html – строка, в которой будет фрагмент HTML с описанием персоны. Присутствует в случае если текст описания имеется в базе и если в запросе был передан параметр descr;
• top_arts ­– массив из наиболее рейтинговых книг, связанных с текущей персоной. Данный массив появляется в ответе только если в запросе был передан параметр top_n_arts. Каждая книга содержит:
  • id* – ID книги;
  • name* – название книги;
  • cover – URL до обложки книги (может быть полным, с доменом, либо относительным);
  • marks – пользовательский рейтинг книги (значение от 0 до 10, например «7.21»);
• top_genres ­– массив из жанров, в которых наиболее широко представлена текущая персона. Данный массив появляется в ответе только если в запросе был передан параметр top_n_genres. Каждый жанр содержит:
  • id* – идентификатор жанра;
  • name* – название жанра;
  • arts_n* – количество книг персоны в этом жанре.

Если не было найдено ни одного автора, удовлетворяющей поисковому запросу, то массив persons будет пустым.

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

Пример запроса на сервер

{
   "app": "1",
   "time": "2014-11-07T16:21:02+03:00",
   "sha": "b79d8e9993d20da6abe78838d3c7fbf640a4c52956569bef3c685d3453316b5c",
   "sid": "7bad5f2fb752ee957a4ab74aaac7711g",
   "requests": [
           {
                 "func": "r_search_persons",
                 "id": "search_persons",
                 "param": {
                   "q": "рой",
                   "limit": ["0","100"],
                   "type": ["0","1","2"],
                   "top_n_arts": "3",         
                   "top_n_genres": "3",         
                   "grammatical_case": "1",   
                   "descr": "1"
                 }
           }
   ]
}

Пример ответа сервера

{
  "success": true,
  "time": "2014-11-07T16:21:02+03:00",
  "search_persons" : {
    "success" : true,
    "persons" : [
        {
          "id": "45142",
          "match_weight": "89",
          "type": "1",
          "last_update": "2015-05-24T11:55:07+03:00",
          "full_name": "Александр Сергеевич Пушкин",
          "first_name": "Александр",
          "last_name": "Пушкин",
          "middle_name": "Сергеевич",
          "last-rodit": "Пушкина",
          "last-dateln": "Пушкину",
          "last-vinit": "Пушкина",
          "last-tvorit": "Пушкиным",
          "last-predl": "Пушкине",
          "full-rodit": "Александра Сергеевича Пушкина",
          "full-dateln": "Александру Сергеевичу Пушкину",
          "full-vinit": "Александра Сергеевича Пушкина",
          "full-tvorit": "Александром Сергеевичем Пушкиным",
          "full-predl": "Александре Сергеевиче Пушкине",
          "inverse-full-name": "Пушкин Александр",
          "arts_n": "32",
          "reviews_n": "22",
          "lvl": "4",
          "img": "http://www.litres.ru/static/authors/100/45142.jpg",
          "description_html": "<p>Великого русского писателя, поэта и драматурга Александра Сергеевича Пушкина знают сегодня во всем мире, что не удивительно, ведь этот талантливейший человек подарил миру такие произведения, как «Евгений Онегин», «Медный всадник», «Дубровский», а также всем знакомые сказки («Сказка о рыбаке и рыбке», «Сказка о мертвой царевне» и др.). Сегодня критики в своих исследованиях называют автора создателем современного русского литературного языка. Ценители русской литературы оставляют отзывы на произведения поэта и стремятся скачать все книги Александра Пушкина в fb2, txt, epub, pdf или других форматах, чтобы загрузить их на свой ПК, ридер или планшет и перечитывать в свободное время. </p>",
            "top_arts": [
              {
                "id": "8604574",
                "name": "Сказки Пушкина",
                "cover": "http://www.litres.ru/pub/c/cover/11399521.jpg",
                "marks": "9.9"
              },
              {
                ...
              }
            ],
            "top_genres": [
              {
                "id": "193",
                "name": "Поэзия",
                "arts_n": "5"
              },
              {
                ...
              }
            ]}, 
          {
            ...
          }
              ...
    ]
  }
}