subtitle

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

ID функции

r_search_arts

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

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

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

q* – строка с поисковым запросом. По умолчанию подбор результатов производится по широким критериям поиска (при этом минимальная длина поискового запроса – 3 символа). Но если вам известно точное название книги, то можно осуществить строгий поиск, указав дополнительный параметр strict="exact". В этом случае минимальная длина поискового запроса – 1 символ;
strict – критерии поиска. Возможные значения:

• no (по умолчанию) – широкие критерии поиска, при которых в названиях книг ищется вхождение каждого слова из поискового запроса. Например, по запросу «рекомендации» будут найдены: «Клинические рекомендации», «Рекомендации лучших специалистов» и др.;
• start – поиск только по книгам, у которых начало названий точно совпадает с поисковым запросом. Например, по запросу «рекомендации» будет найдена книга «Рекомендации лучших специалистов», а вот «Клинические рекомендации» в ответ уже не попадет;
• exact – поиск книг, название которых полностью совпадает с поисковым запросом. Например, по запросу «сон» будут найдены только книги с названием «Сон». А «Сонеты» или «Сон разума» в ответ не попадут.

limit – ограничение на количество возвращаемых книг. Работает аналогично инструкции limit в MySQL и в запросе представлен одним числом либо массивом из двух чисел «N,M». Если limit указан, возвращается M книг, начиная с книги N (у первой книги номер 0). Если limit не задан – значение по умолчанию «0, 20»;
anno – если параметр имеет значение «1» или «2», то в ответе к найденным книгам будут добавлены аннотации (см. annotation);
biblio_fund - если параметр имеет значение «1», то в ответе будут только книги, имеющиеся в фондах библиотек, к которым подключен пользователь
currency – валюта, в которой необходимо возвращать цены InApp'ов на книги. Если параметр не передан информация по InApp'ам (inapp_price, inapp_name) не возвращается. Допустимые значения:

• RUB – российские рубли (по умолчанию);
• USD – доллары США;
• EUR – евро;
• PLN – польские злотые.

atype – параметр для запроса книг определенных типов (super_art_types). Если параметр не передан, в ответе будут выданы книги всех типов. Допустимые значения:

• 1 – электронные книги;
• 2 – аудиокниги;
• 10 – подкасты;
• 11 – выпуски подкастов.

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

arts* – массив объектов, содержащий найденные книги. Информацию по каждой книге условно можно разбить на три подраздела:

• подраздел 1, в котором содержится каталожное описание книги:
  • id* – ID книги;
  • match_weight* – степень релевантности найденного произведения (значение от 0 до 100, где 100 – максимально релевантно; 0 – наименее релевантно). Учитывает как степень совпадения поискового термина с запросом, так и популярность целевого произведения;
  • last_update* – время последних изменений (любых) описания или содержания книги в формате «ГГГГ-ММ-ДД ЧЧ:ММ:СС»;
  • last_release* – время последнего «релиза» книги – изготовления итогового файла для чтения. Возможно, если время изменилось, стоит скачать последнюю версию файла книги. Формат времени: «ГГГГ-ММ-ДД ЧЧ:ММ:СС»;
  • lvl* – экспертный рейтинг книги (целое значение от 1 до 5). Отражает ценность книги с точки зрения продаж: 1 – «мусорная» книга, а 5 – гарантированный бестселлер;
  • type* – тип книги. Возможные значения:
    • 0 – электронный текст (FB2/FB3);
    • 4 – PDF-книга;
    • 1 – аудиокнига;
    • 11 – Gardner books;
    • 22 – подкаст;
    • 23 – выпуск подкаста.
  • alien* – принадлежность книги иностранному правообладателю. Возможные значения:
    
    • 4 – Gardners;
    • 8 – Ozon.ru;
    • 9 – Olesiejuk;
    • 10 – Azymut;
    • 11 – PDW;
    • 12 – EDK;
    • 13 – Bookwire Soft;
    • 14 – Bookwire No DRM;
    • 15 – Yandex TTS;
    • 16 – Ingram;
    • 17 – Ingram No DRM;
    • 18 – Zebralution;
    • 19 – Harper Collins (USD);
    • 20 – Harper Collins (EUR);
    • 21 – Harper Collins (GBR);
  • drm* – наличие DRM-защиты. Возможные значения:
    • 0 – DRM-защита отсутствует;
    • 3 – книга защищена ЛитРес DRM.
  • title* – название книги;
  • subtitle ­– подзаголовок к названию книги;
  • subscr_podcast - 1 или не приезжает в зависимости от наличия подписки на подкаст.
  • lang* – язык книги (трехбуквенное ! обозначение по ISO 639-3);
  • chars* – число символов в электронной книге (type=0). В случае с PDF-книгой (type=4) к символу приравнивается страница, для аудиокниг (type=1) – секунда звучания;
  • sequences – массив с сериями, к которым принадлежит книга:
    • id* – ID серии;
    • name* – название серии;
    • sequence_number – порядковый номер книги в данной серии;
    • reviews_n – общее количество отзывов (рецензий), оставленных к серии и одобренных модераторами;
    • arts_n – общее количество книг в серии;
    • disabled – 1 для серий, навигация по которым недоступна (если книга была куплена/залита в облако, но сейчас недоступна как и другие книги серии). Иначе отсутствует.
  • persons – массив, содержащий информацию о всех персонах книги (см. запрос поиска персон). Каждая персона описана следующими элементами:
    • id* – ID персоны;
    • full_name* – полное ЛитРес-название персоны;
    • img – URL до фотографии персоны (может быть полным, с доменом, либо относительным);
    • type – тип персоны (см. type в запрос поиска персон, кроме type=2);
    • disabled – 1 для персон, навигация по которым недоступна (если книга была куплена/залита в облако, но сейчас недоступна как и другие книги автора). Иначе отсутствует.
  • genres* – массив с жанрами книги:
    • id* – ID жанра;
    • name* – название жанра;
    • is_tag – признак, что это тег, а не полноценный жанр;
    • disabled – 1 для серий, навигация по которым недоступна (если книга была куплена/залита в облако, но сейчас недоступна как и другие книги тега/жанра). Иначе отсутствует.
  • cover – obsolete, раньше тут передавался URL до обложки книги (может быть полным, с доменом, либо относительным). Сейчас см. ниже блок «Получение обложки, триального фрагмента и XML-содержания книги»;
  • cover_h – высота обложки в пикселях;
  • cover_w – ширина обложки в пикселях;
  • date_written – дата записи;
  • images – число иллюстраций в электронной книге (type=0);
  • annotation – строка с фрагментом описания к книге в формате аннотации к FB3-книге: fb3-description/annotation (абзацы p, пустые строки br, ссылки a, форматирование текста жирным strong и курсивным em начертанием). Данное описание присутствует в ответе только, если в запросе был передан параметр anno, и в базе в принципе есть описания к этой книге; Если передан параметр anno=1, аннтоация берется из arts.text_html_annotation, если 2 – то добавляется (если есть) аннотация из arts_annotations.text_html_annotation_lib.
  • minage* – минимальный возраст читателя для данной книги. «0» означает, что книга не имеет возрастных ограничений;
  • isbn – ISBN книги (если электронной версии ISBN не присвоен – отдаёт ISBN бумажной версии, если нет и его – ничего);
  • publisher – правообладатель (издательство);
  • finish – возвращается значение «1», если книга прочитана пользователем, иначе этот параметр будет отсутствовать;
  • year_written – дата написания;
  • first_time_sale – время, когда книга впервые попала в продажу на ЛитРес;
  • exp_chars – ожидаемое число символов (см. chars выше) в полной книге, появляется у Черновика (наличие поля указывает, что данная книга – черновик). Может равняться 0, что означает что данная книга – черновик, но ожидаемый размер полной книги неизвестен. Может встречаться у книг типа 0 и 4;
  • exp_update_freq – ожидаемая периодичность обновлений черновика (в днях). Может отсутствовать даже для черновика, что означает что периодичность автором не зафиксирована. Может встречаться у книг типа 0 и 4;
• подраздел 2, в котором описывается возможность покупки или бесплатного получения книги, её цена, а также её наличие у текущего пользователя:
  • base_price* – базовая цена книги в рублях;
  • final_price* – итоговая цена книги в рублях с учётом активных скидок («магия», определяющая какую часть покупки можно оплатить бонусами и пр. здесь не учитывается);
  • inapp_price – цена InnApp'а в запрошенной валюте (см. currency в запросе);
  • inapp_name – название InnApp'а;
  • free – признак бесплатной книги (если «1» – книга доступна бесплатно);
  • azimyt_trial – признак наличия у книги ознакомительного фрагмента. Возвращается значение = 1 для книг c параметром alien=10;
  • pdw_trial – признак наличия у книги ознакомительного фрагмента. Возвращается значение = 1 для книг c параметром alien=11;
  • in_gifts ­­– признак, что пользователь может «взять себе» эту книгу (например, «1» или «5» – может взять себе). Числовое значение – сколько ещё пользователь может взять книг;
  • in_basket – признак того, что книга находится в корзине пользователя, но еще не куплена. Значение этого объекта – ID записи в корзине;
  • my ­– признак того, что эта книга уже уже куплена/получена этим пользователем:
    • 1 – эта книга уже есть у пользователя (куплена, получена, доступна для скачивания);
    • 2 – книга куплена по предварительному заказу, но недоступна для скачивания.
  • files_pending – признак того, что файл fb3 или mp3 еще готовится, чтобы стать доступным к скачиванию. Может принимать только значение =1 (если файл книги доступен, то параметр не возвращается). При этом в ответе атрибут my=1. Возвращается только книгам с alien=4, 10, 11;
  • biblio_selfservice – признак того, что текущий пользователь является простым или гибридным библиотечным читателем. Возможные значения:
    • delayed – книга доступна для выдачи в библиотеке после запроса;
    • instant – книга доступна для выдачи в библиотеке сразу. Например, если это «коммерческая» библиотека или обычная, но с режимом самообслуживания, когда у пользователя достаточно прав, чтобы «Взять себе», а у библиотеки – достаточно финансов, чтобы оплатить эту книговыдачу;
    • impossible – книга недоступна для выдачи через библиотеку;
    • requested – читатель отправил в библиотеку запрос на получение книги и ожидает его одобрения;
    • received – книга уже получена пользователем (при этом my=1).
  • valid_till – время, до которого данная книга доступна пользователю. В текущий момент используется в библиотечном проекте, т. е. у книги, выданная библиотекой, в ответе будут следующие атрибуты: my=1, biblio_selfservice='received' и valid_till='2020-01-01 12:00:00'. Но в дальнейшем поле может иметь и другой смысл, так что клиент должен в ЛЮБОМ случае смотреть на него при my=1 и при истечении срока удалять эту книгу у пользователя;
  • biblio_fund – число книг в библиотечном фонде;
  • biblio_busy – в том числе число книг из фонда «на руках»;
  • biblio_queue_size – размер очереди на книгу в библиотеке;
  • avail_by_subscr – признак доступности книги к выдаче при активной подписке пользователя («1» – книга доступна по подписке, иначе «0»);
  • my_subscr – признак чтения книги по подписке (значение «1» – пользователь взял книгу по подписке, иначе атрибута нет);
  • available – признак доступности книги:
    • -1 – скрыть карточку (в обычные артовые списки не приходит, в основном в r_my_arts_all);
    • 0 – книга не в продаже;
    • 1 – книга доступна и в продаже;

    • 2 – книга скоро поступит в продажу (дата неизвестна);

    • 6 – книга поступит в продажу, дата известна;

  • available_date – дата поступления книги в продажу (отдается при наличии в базе, используется для available=6);
  • can_preorder – признак, указывающий на возможность оформить предварительную покупку на книгу, которая должна поступить в продажу и уже имеет известную цену:
    • 0 – книга недоступна для предоплаты;
    • 1 – книга доступна для предоплаты;

  • preorder_subscr – признак того, что пользователь подписался на уведомление о старте продаж этой книги. Если вернулось значение «1», значит такая подписка у пользователя есть;

  • draft_subscr – если вернулось значение «1», то книга является аудиочерновиком, и пользователь при этом на нее подписан. Иначе этот параметр будет отсутствовать в ответе;
  • book_avail_by_subscr – признак доступности книги для взятия себе в рамках программы «ЛитРес: Абонемент», если у пользователя она НЕ подключена (значит, что книга удовлетворяет условиям по цене);
  • subscription_book – если вернулось значение «1», то пользователь может взять эту книгу себе в рамках программы «ЛитРес: Абонемент», если у пользователя она подключена;
  • arts_no_discount – если вернулось значение «1», значит для этой книги запрещено применять любые скидочные программы;
  • subscription_forbidden – если вернулось значение «1», значит эту книгу запрещено выдавать пользователям в рамках программы «ЛитРес: Абонемент»;

  • parent_podcast_name – имя подкаста-родителя, возвращается только для выпуска подкаста (type=23);

  • parent_podcast_id – ID подкаста родителя, возвращается только для выпуска подкаста (type=23);

  • podcast_serial_number – номер выпуска подкаста в сборнике, возвращается только для выпуска подкаста (type=23);
• подраздел 3, в котором описываются рецензии, рейтинги и оценки книги:
  • reviews_n – общее количество отзывов (рецензий), оставленных к книге и одобренных модераторами;
  • mark_1 – общее кол-во пользователей, оценивших данную книгу на «1»;
  • mark_2 – общее кол-во пользователей, оценивших данную книгу на «2»;
  • mark_3 – общее кол-во пользователей, оценивших данную книгу на «3»;
  • mark_4 – общее кол-во пользователей, оценивших данную книгу на «4»;
  • mark_5 – общее кол-во пользователей, оценивших данную книгу на «5»;
  • user_mark – оценка книги текущим пользователем (целое значение от 1 до 5). Если текущий пользователь не голосовал за эту книгу – параметр отсутствует.
  • ll_marks_n – количество оценивших на Livelib;
  • ll_avg_marks – средняя оценка на Livelib.

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

Получение обложки, триального фрагмента и XML-содержания книги

Дополнительные материалы по книге получаются по её ID.

Получение обложки книги

URL обложки формируется по шаблону https://cv(#1).litres.ru/pub/c/cover_(#2)/(#3).jpg. Например, https://cv3.litres.ru/pub/c/cover_200/28070137.jpg, где:

• #1 – ID сервера с картинками. Значение может быть в диапазоне «0-9». Следует использовать предпоследнюю цифру из ID книги (десяток). Для книги с ID 4568 это будет 6, для книги с ID 1599974 – 7. Использование десятка позволит равномерно нагружать серверы и при этом эффективно обеспечивать на каждом из них локальное кэширование. Для недоступных книг вместо cv# используется основной домен, на котором приложение авторизовалось (см. ниже).
• #2 – размер обложки:
  • может отсутствовать. При этом будет просто /cover/. Например, https://cv3.litres.ru/pub/c/cover/28070137.jpg); В этом случае мы должны дернуть заведомо известный размер переконвертированной обложки, опираясь на факт, что у нас не может быть непереконвертированных обложек.
  • может указывать на требуемую ширину изображения. Указывается число /cover_200/. Например, https://cv3.litres.ru/pub/c/cover_200/28070137.jpg. Запросить можно только одно из предопределенных значений;
  • может указывать на требуемую высоту изображения. При этом указывается _h+число /cover_h190/. Например, https://cv3.litres.ru/pub/c/cover_h190/28070137.jpg. Запросить можно только одно из предопределенных значений;
  • может указывать на размер по длинной стороне. При этом указывается _max+число/cover_max1500/. Например, https://cv3.litres.ru/pub/c/cover_max1500/28070137.jpg. Запросить можно только один из предопределенных «максимальных размеров».
• #3 – ID книги, см. выше id. ID используется «as-is», без дополнения нулями до необходимого числа разрядов. Для книги с ID 28070137 обложка будет доступна на https://cv3.litres.ru/pub/c/cover_200/28070137.jpg.

Если обложка относится к недоступной книге (например, к залитой пользователем), то домен должен быть указан тот же, на который заходит приложение, используя данный метод API. При этом в cookies или параметрах должен быть передан SID. Например, для залитого пользователем арта с ID 28070138 на домен litres.ru URL будет таким: https://catalit2.litres.ru/pub/c/cover_200/28070138.jpg?sid=7bad5f2fb752ee957a4ab74aaac7711g. 

Получение toc.xml (оглавления книги)

URL формируется аналогично обложке, но без указания размера, при этом расширение ставится XML. Например, для получения содержания книги с ID=28070137 нужно использовать URL: https://cv3.litres.ru/pub/c/cover/28070137.xml.

Получение ознакомительного фрагмента

URL для получения ознакомительного фрагмента (www, pda) формируется по шаблонам:

• для книг типа «0» (fb3, epub, fb2.zip) – https://cv(#1).litres.ru/pub/t/(#3).<ext> (расшифровку #1 и #3 см. выше в разделе «Получение обложки книги»). Ознакомительный фрагмент может быть доступен в форматах fb3, epub, fb2.zip, если эти форматы присутствуют для полной книги. Например, https://cv3.litres.ru/pub/t/28070137.fb3;
• для книг типа «4» (pdf) – https://cv(#1).litres.ru/get_pdf_trial/(#3).pdf;
• для книг типа «1» (аудио книги) – https://cv(#1).litres.ru/get_mp3_trial/(#3).mp3.

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

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

{
   "app": "1",
   "time": "2014-11-07T16:21:02+03:00",
   "sha": "b79d8e9993d20da6abe78838d3c7fbf640a4c52956569bef3c685d3453316b5c",
   "sid": "7bad5f2fb752ee957a4ab74aaac7711g",
   "requests": [
           {
                 "func": "r_search_arts",
                 "id": "search_arts",
                 "param": {
                   "q": "Оне",
                   "strict": "start",
                   "limit": ["0","5"],
                   "anno": "1",        
                   "currency": "RUB"
                 }
           }
   ]
}

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

{
   "success": true,
   "time": "2014-11-07T16:21:02+03:00",
   "search_arts" : {
      "success" : true,
      "pages" : "2",
      "arts" : [
       {
         "id" : "171966",
         "match_weight" : "90",
         "last_update" : "2014-02-01T06:27:05+03:00",
         "last_release" : "2014-02-01T06:27:05+03:00",
         "lvl" : "5",
         "type" : "0",
         "drm" : "0",
         "title" : "Евгений Онегин",
         "subtitle" : "Второе издание",
         "lang" : "rus",
         "chars" : "201276",
         "sequences" : [
           {
             "id" : "185259",
             "name" : "Список школьной литературы 9 класс",
             "sequence_number" : "21",
             "reviews_n " : "1",
             "arts_n" : "31",
           },
           {
              ...
           },
         ],{
         "persons" : [
             {
               "id" : "45142",
               "full_name" : "Александр Сергеевич Пушкин",
               "img" : "http://www.litres.ru/static/authors/100/45142.jpg",
               "type" : "1",
             },
             {
               ...
             }
         ],
         "genres" : [
           {
             "id" : "193",
             "name" : "Поэзия",
             "is_tag" : "1"
           },
           {
              ...
           },
         ],
         "cover" : "/pub/c/cover/08787189.jpg",
         "cover_h" : "798",
         "cover_w" : "570",
         "images" : "3",
         "annotation" : "<p>В книгу вошел роман в стихах А.С.Пушкина (1799–1837) «Евгений Онегин», обязательный для чтения и изучения в средней общеобразовательной школе.</p>
<p>Роман в стихах «Евгений Онегин» стал центральным событием в литературной жизни пушкинской поры. И с тех пор шедевр А.С.Пушкина не утратил своей популярности, по-прежнему любим и почитаем миллионами читателей.</p>",
         "minage" : "0",
         "base_price" : "0",
         "final_price" : "0",
         "inapp_price " : "29.95",
         "inapp_name" : "ru.litres.app.refill_99.XXL",
         "free" : "1",
         "in_gifts" : "1",
         "in_basket" : "466557",
         "my" : "1",
         "biblio_selfservice" : "received",
         "valid_till" : "2015-12-01T12:00:00+03:00",
         "avail_by_subscr" : "1",
         "my_subscr" : "1",
         "reviews_n" : "15",
         "mark_1" : "2",
         "mark_2" : "12",
         "mark_3" : "10",
         "mark_4" : "33",
         "mark_5" : "23",
         "user_mark" : "5"
       },
       {
         ...
       },
       {
         ...
       }
    ]
  }
}