API

Материал из КиноВики

Перейти к: навигация, поиск

Содержание

[править] Общие сведения

Домен API: http://api.kinobaza.tv

Email для вопросов, предложений и багрепортов: get.api@kinobaza.tv

Формат ответов: Content-type: application/json, charset=utf-8


[править] Обработка ошибок

В случае ошибки, ответ от сервера возвращается с соответствующим заголовком статуса, а в теле передается JSON объект вида: 

{
    code: <код ошибки>
    message: <описание ошибки>
}

[править] Возможные коды ответа сервера

Ошибки сервера соответствуют статус-кодам HTTP:

  • 200 - OK
  • 401 - требуется авторизация
  • 403 - доступ запрещен
  • 404 - запрашиваемый документ не найден
  • 405 - неправильный метод запроса. Вероятно вместо POST использовался GET метод.
  • 503 - превышено кол-во допустимых запросов в секунду


[править] Медиа

Все графические медиа располагаются на домене: http://media.kinobaza.tv

Для получения конкретной графики, используйте следующие URL:

  • постер фильма: /films/<film_id>/poster/<width>.jpg (width = 207, 60, 40)
  • фотография актера/режисера/пр.: /persons/<person_id>/photo/60.jpg
  • аватар пользователя: /users/<user_id>/avatar/<width>.png (width = 150, 30)

[править] Категории запросов

[править] Авторизация

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

[править] Правильный. Через OAuth

Авторизация сайтов и приложений, для которых возможно использование браузера, проходит через OAuth (библиотеки для разных языков, общие сведения). Это самый правильный метод идентификации приложения при обращении к API от имени пользователя.

Подключить свой сайт или приложение и получить ключи можно по адресу: http://kinobaza.tv/applications/my

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

server_uri: http://api.kinobaza.tv/
signature_methods: PLAINTEXT
request_token_uri: http://api.kinobaza.tv/auth/request-token
authorize_uri: http://api.kinobaza.tv/auth/authorize
access_token_uri: http://api.kinobaza.tv/auth/access-token


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

[править] НедоOAuth. Через PIN код

Для приложений, которые не имеют возможности открыть браузер, либо по другим причинам не могут использовать полноценный OAuth, доступна авторизация по PIN кодам. Для этого на шаге получения request token'а от кинобазы, в обычный сценарий вводится дополнительный возвращаемый параметр: kinobaza_access_pin. Для получения доступа, приложение должно попросить пользователя перейти по ссылке: 

   http://kinobaza.tv/my/search-application-by-pin?pin=<pin>

либо ввести полученный PIN-код на странице: 

   http://kinobaza.tv/my/applications

и разрешить приложению доступ, после чего, приложение может продолжать обычный OAuth сценарий (получить access token, сохранить его и подписывать дальнейшие запросы им)


[править] По email и паролю

Для подключения доступа к этим методам, необходимо предварительно согласовать условия со службой поддержки. Пишите на get.api@kinobaza.tv с подробностями для чего нужны эти методы и почему не подходят существующие способы авторизации

Самым неправильным методом доступа к пользовательским данным может служить вход по email/паролю. Для этого необходимо обратиться к методу /auth/login-by-email с правильными данными и в ответе получить пару access_token и access_token_secret, которые нужно использовать для дальнейшей работы по спецификации OAuth.

Также возможно создать нового пользователя на кинобазе, используя метод /auth/register.

Если у пользователя уже есть аккаунт на Кинобазе, в который он логинится не по email и паролю, а другим способом, но сейчас доступа к браузеру нет, пользователь может создать временный аккаунт с логином по email и паролю, который позже привяжет к основному аккаунту через настройки на сайте.

Метод Параметры Описание
POST /auth/register email string email пользователя. С ним можно будет войти на сайте + на него будут высланы данные регистрации создает нового пользователя на кинобазе
password string пароль пользователя произвольной длинны
POST /auth/login-by-email consumer_key string ключ приложения, полученного при регистрации приложения на Кинобазе выполняет вход пользователя по email и паролю и возвращает действующие access_token и access_token_secret
email string email пользователя
password string пароль пользователя

[править] Фильмы

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

Для примера рассмотрим метод /films/browse. Необходимо получить кроме идентификаторов фильмов еще и их краткие сведения, жанры к которым каждый фильм относится и рейтинги на других сайтах. Для этого, найдем соответствующие значения в таблице. Это 1, 8 и 32. Просуммируем их: 1 + 8 + 32 = 41. Это и есть значение параметра, которое нужно передавать в запросе: 

   /films/browse?fields_mask=41


[править] Общие методы

Метод Параметры Описание
GET /films/browse ids array список идентификаторов фильмов для поиска Фильтр фильмов по параметрам

Ограничения:

  • если параметр fields установлен в none - максимальный limit равен 1000
  • если параметр fields не none - максимальный limit 100
  • offset + limit не может превышать 10000 (limit будет автоматически уменьшен)
type string Тип фильтруемых результатов (movie/series)
fields_mask int битовая маска набора полей результата
genres array идентификаторы жанров для поиска
genres_not array идентификаторы жанров, которые нужно исключать из результатов
genres_mode string применяемая логика к массиву genres. Если and, то выбираются фильмы у которых есть все перечисленные жанры, если or - в фильме должен быть любой из перечисленных жанров
languages string (временно не доступно)
participants array список идентификаторов участников фильма (актеры, режиссеры и т.д.)
countries array идентификаторы стран
countries_not array идентификаторы стран для исключения
imdb_rating_max float максимальный рейтинг imdb [0,10]
imdb_rating_min float минимальный рейтинг imdb [0,10]
kinopoisk_rating_max float максимальный рейтинг кинопоиска [0,10]
kinopoisk_rating_min float минимальный рейтинг кинопоиска [0,10]
imdb_rating_voted_min int минимальное кол-во голосов за фильм на imdb
kinopoisk_rating_voted_min int минимальное кол-во голосов за фильм на кинопоиске
year_max int максимальный год релиза фильма
year_min int минимальный год релиза фильма
dubbing_types array (временно недоступно)
qualities int среднее+, хорошее+, HD+ [2/3/4]
sort int порядок сортировки (временно int 1 - по imdb, 2 - по кинопоиску, 3 - по дате выхода, 4 - по времени появления на трекерах)
limit int кол-во фильмов в результате
offset int смещение от начала результатов
hide_marked 0/1 исключить из результатов фильмы, отмеченные пользователем (как seen, starred, deleted и watching)
GET /films/<film_id> fields_mask int маска для выборки наборов полей выводит информацию о конкретном фильме
GET /films/search query string строка запроса Поиск фильмов по названию, отсортированных по релевантности.
limit integer кол-во возвращаемых результатов (default=100, max=100)
offset integer смещение результатов относительно начала (default=0)
fields_mask integer битовая маска получаемой информации о фильме (default=1)
GET /films/search-by-file filepath string полный путь к файлу (включая его имя) Пытается найти соответствие фильма по хешу заголовка физического файла и/или названию файла (временно не работает поиск эпизодов и не используется название файла).

Хеши рассчитываются путем получения sha1 хеша первого мегабайта данных в виде hex значения (40 символов)

hash array sha1 хеш первого мегабайта файла в hex представлении
GET /films/lookup names array массив вариаций названий фильма Поиск фильма по известным данным о нем.

Например мы знаем название, год выпуска и два жанра - нужно найти соответствие на Кинобазе.

years array известные годы, в которые выпускался фильм
type string тип фильма ( "movie" / "series" )
participant_names array список имен участников фильма (актеры/режиссеры/продюсеры и пр)
duration_seconds integer длительность фильма в секундах
country_ids array идентификаторы стран-производителей
genre_ids array идентификаторы жанров фильма
links array ссылки на фильмы на других источниках в формате array( <source_id> => <film_id> ). Например для фильма "Схватка": ?links[kinopoisk.ru]=571
GET /films/<series_id>/seasons Список сезонов сериала
GET /films/<series_id>/seasons/<season_num> Информация об одном сезоне сериала
GET /films/<series_id>/seasons/<season_num>/episodes Список эпизодов сезона
GET /films/<series_id>/seasons/<season_num>/episodes/<episode_num> Информация об одном эпизоде

I'm not whroty to be in the same forum. ROTFL

[править] Пользователь

Все методы из этого блока требуют предварительной авторизации пользователя.

Метод Параметры Описание
GET /my/films/by-status status string значение из таблицы статусов фильмов (см. ниже) Возвращает список фильмов по статусу пользователя
+ любые параметры из метода /films/browse, кроме type. Для получения пользовательских сериалов предусмотрены методы ниже (/my/series/*)
GET /my/films/get-status ids array / int идентификатор или массив идентификаторов фильмов, для которых нужно получить статус
GET /my/series/unseen-episodes series_id array идентификаторы сериалов, возвращает список не просмотренных серий для сериалов. Если параметр отсутствует, выводится результат для всех сериалов, которые пользователь отметил как "смотрю".
GET /my/series/seen Список сериалов, которые пользователь когда-либо смотрел
GET /my/series/want-to-see параметры как у /films/browse Список сериалов, которые пользователь отметил "хочу посмотреть"
GET /my/series/do-not-want-to-see параметры как у /films/browse Список сериалов, которые пользователь отметил "не показывать"
GET /my/series/watching параметры как у /films/browse Список сериалов, которые пользователь отметил как "смотрю"
GET /my/subscriptions Возвращает список подписок на фильмы/сериалы
GET /my/subscriptions/films Возвращает список подписок на фильмы
GET /my/subscriptions/films/completed limit integer максимальное кол-во результатов Возвращает список завершенных подписок на фильмы
offset integer смещение результатов от начала
GET /my/subscriptions/films/unreaded Возвращает список подписок на фильмы, которые пользователь еще не отметил просмотренными
GET /my/subscriptions/series Возвращает список подписок на сериалы
POST /my/subscriptions/add torrent_url string полный URI описания торрента, на обновление которого нужно подписаться Создает/изменяет подписку на фильм/сериал. Если передан параметр torrent_url, то остальные параметры игнорируются. Если подписка создается на новые серии у сериала, а параметры season и episode не указаны, то создается подписка на новые серии после последней доступной.
film_id integer идентификатор фильма/сериала
quality string значение ожидаемого качества видео (из констант)
dubbing string значение ожидаемой озвучки (из констант)
sources_logic string логика подписки на источники (из констант)
tracker_ids array идентификаторы трекеров, на которых отслеживается появление релизов для этой подписки
season integer порядковый номер сезона с которого нужно начинать получать уведомления
episode integer порядковый номер серии, после которой будут приходить уведомления
languages_ids
 array
 массив идентификаторов языков из метода /languages для подписки на определенный перевод/дубляж
POST /my/subscriptions/<id>/remove id integer идентификатор подписки удаляет подписку на фильм/сериал
GET /my/trackers Список отслеживаемых пользователем трекеров
GET /my/trackers/set ids array массив идентификаторов трекеров Устанавливает пользователю отслеживаемые трекеры
POST /my/films/set-status id int идентификатор фильма Устанавливает статус фильму
status string статус из таблицы статусов фильмов (default=seen)
rate int оценка фильма [0,10]
POST /my/series/mark-seen/ series_id int идентификатор сериала Отмечивание сериала/сезона/серии просмотренными, в зависимости от переданного набора параметров

Если inclusive равен true - у сериала отмечаются просмотренными все серии по сезон <season> и эпизод <episode> включительно. Если были отмечены просмотренными серии после <season>:<episode> - отметка с них сбрасывается.

season int порядковый номер сезона
episode int порядковый номер серии в сезоне
inclusive boolean отметить ли все предыдущие серии?
POST /my/series/mark-not-seen series_id int идентификатор сериала Сбрасывает отметку о просмотре сериала/серии/сезона

Если передан только <season>, но не <episode> - сбрасываются отметки о просмотре всех серий в данном сезоне Если не переданы ни <season> ни <episode>, весь сериал отмечается как не просмотренный

season int порядковый номер сезона
episode int порядковый номер серии в сезоне

[править] Другое

Метод Параметры Описание
GET /genres Список доступных жанров
GET /countries Список доступных стран
GET /languages Список известных языков
GET /trackers Список поддерживаемых трекеров
GET /torrents/<hash>/direct-link hash string hex значение хеша торрента (40 символов) Получение прямой ссылки для скачивания торрента без регистрации на трекере и без учета рейтингов. Доступно только для улучшенных аккаунтов. В API получить хеш можно в ответе на запрос списка торрентов к фильму/серии.


[править] Биллинг

Метод Параметры Описание
GET /payments/sms/countries Список доступных стран для оплаты улучшенного аккаунта по СМС
GET payments/sms/countries/<country_name> country_name string название страны из метода /payments/sms/countries возвращает список операторов мобильной связи в стране
GET payments/sms/countries/<country_name>/<operator_id> country_name string название страны из метода /payments/sms/countries возвращает информацию для СМС платежа на конкретном операторе в стране
operator_id integer идентификатор оператора в стране

[править] Константы и таблицы значений

[править] Возможные группы выборки данных о фильмах (fields_mask)

  • 0 - только идентификаторы
  • 1 - самая базовая информация (тип, название, оригинальное название, год выпуска, продолжительность, лучшее доступное качество на трекерах)
  • 2 - описание
  • 4 - список актеров/режиссеров (если ожидается больше одного фильма - ограничение по 10 человек на тип участия)
  • 8 - список жанров
  • 16 - страна-производитель, сборы, бюджет
  • 32 - рейтинги на различных ресурсах Сети (рейтинг и кол-во голосов)


[править] Возможные статусы фильмов

  • none - статус сброшен или отсутствует
  • seen - фильм или серия просмотрены
  • deleted - не отображать фильм в списках
  • starred - хочу посмотреть
  • watching - для сериала. смотрю в настоящий момент


[править] Константы участников фильма

  • actor - Актёр
  • director - Режиссёр
  • writer - Сценарист
  • producer - Продюсер
  • operator - Оператор
  • composer - Композитор


[править] Константы используемые в подписках

[править] Параметры озвучки

  • any - любая озвучка.
  • original - появилась раздача с оригинальной озвучкой.
  • translated - появилась раздача с переводом (одно-/многоголосым).
  • dubbed - появилась раздача с дублированным переводом.

[править] Параметры качества

Тут имеется ввиду наименьшее ожидаемое качество раздачи. Если появится качество лучше, чем то, на которое оформлена подписка, уведомление придет все-равно. Например если есть подписка на low, а появилась раздача в hd то пользователь будет о ней оповещен.

  • any - любое качество видео в раздаче
  • low - появился релиз типа CAMRip, VHSRip, TeleSync
  • medium - появился релиз типа TVRip, SATRip, а также другие релизы, у которых ширина картинки меньше 590 пикселей
  • high - остальные релизы, у которых размер картинки до 1000 пикселей
  • hd - HD-качеством считаются HDRip, HDTVRip, BDRip и другие релизы, разрешение которых равно 720p или больше

[править] Параметры подписки на источники появления релиза

  • any - любой из доступных на Кинобазе источник
  • any_my - раздача появится на любом из отмеченных пользователем трекере в разделе "Мои трекеры"
  • exact - раздача станет доступна на конкретном из указанных пользователем трекере

[править] Примеры реализаций работы с API

Для реализация под Java будет полезным использование библиотек:

  • google-gson - конвертация JSON в объекты Java
  • oauth-signpost - простой OAuth клиент, готовый для работы с Android

Для C# полезной оказалась библиотека:

  • Json.NET - неимоверно упрощает работу конвертации JSON в объекты C#

[править] Примеры приложений

  • Totem скробблер. Автоматически отмечает фильмы во время просмотра их в плеере totem.

[править] Условия использования

Доступ к API предоставляется абсолютно свободно, ограничивая лишь кол-во запросов в секунду (на данный момент 3r/sec). Но если вы решите поставить на нас активную ссылку, мы вовсе не будем против :)

Источник — «http://wiki.kinobaza.tv/API»