Списки и пагинация

Все списки API устроены одинаково: каталог и поиск, чарты, подборки, состав, медиа, фильмография. Разобрав форму один раз, вы прочитаете любой список.

Форма списка

curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "q=матрица" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_imdb" \
  "https://api.kinodata.space/v1.3/titles"

Ответ200

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_ru": "Матрица",
      "title_en": "The Matrix",
      "year": 1999,
      "rating_imdb": 8.7
    },
    {
      "imdb_id": "tt0234215",
      "kp_id": "299",
      "tmdb_id": "604",
      "tmdb_tv_id": null,
      "kinorium_id": "190315",
      "title_ru": "Матрица: Перезагрузка",
      "title_en": "The Matrix Reloaded",
      "year": 2003,
      "rating_imdb": 7.2
    },
    {
      "imdb_id": "tt0242653",
      "kp_id": "316",
      "tmdb_id": "605",
      "tmdb_tv_id": null,
      "kinorium_id": "196883",
      "title_ru": "Матрица: Революция",
      "title_en": "The Matrix Revolutions",
      "year": 2003,
      "rating_imdb": 6.7
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}

поле	что это
`items`	Элементы списка.
`total`	Сколько элементов всего. `null`, если API их не считает — об этом ниже.
`limit`	Сколько элементов на странице. Если вы попросили больше, чем можно, здесь будет настоящее число.
`offset`	Сколько элементов пропущено от начала.
`has_more`	Есть ли следующая страница.
`next_cursor`	Курсор следующей страницы. Только когда вы листаете курсором.

Поля самого ресурса приходят рядом: roles у состава и фильмографии, counts у связей и текстов, collection у подборки.

Когда total равен null

Список бывает двух видов.

Набор задан адресом: состав тайтла, его связи и медиа, фильмография человека, подборка. Такой набор конечен, и total — число.
Набор задан запросом: каталог и поиск, топ, скрытые жемчужины, поиск людей. Здесь total: null: точный подсчёт по фильтру — второй проход по всей базе на каждой странице. Чтобы понять, есть ли ещё, смотрите на has_more. Расхождения оценок и календарь релизов считают total и с фильтрами.

Сколько элементов на странице

список	по умолчанию	максимум
Каталог и поиск, чарты, витрины, календарь релизов, подборки, поиск людей	50	50
Состав, медиа, тексты, связи, серии, фильмография, совместные работы	1000	1000
Разделы, когда список разбит на них	10 в разделе	50 в разделе

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

limit — целое число от 1, offset — от 0. Число больше максимума не ошибка: API уменьшит его и вернёт настоящее значение в limit. limit=5000 в каталоге даст "limit": 50. Ноль, отрицательное число или не число — ошибка 400.

Страницы: offset

?limit=50&offset=100

offset — сколько элементов пропустить. Следующая страница — offset плюс limit, пока has_more равно true.

Глубокая прокрутка: cursor

Для долгого листания каталога /titles берите курсор: он не сбивается, если база меняется, пока вы листаете. Передайте пустой cursor= — в ответе появится next_cursor:

curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "limit=2" \
  --data-urlencode "fields=title,rating_imdb" \
  --data-urlencode "cursor=" \
  "https://api.kinodata.space/v1.3/titles"

Ответ200

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0903747",
      "kp_id": "404900",
      "tmdb_id": null,
      "tmdb_tv_id": "1396",
      "kinorium_id": "400796",
      "title_ru": "Во все тяжкие",
      "title_en": "Breaking Bad",
      "rating_imdb": 9.5
    },
    {
      "imdb_id": "tt5491994",
      "kp_id": "1007472",
      "tmdb_id": null,
      "tmdb_tv_id": "68595",
      "kinorium_id": "1605088",
      "title_ru": "Планета Земля 2",
      "title_en": "Planet Earth II",
      "rating_imdb": 9.4
    }
  ],
  "limit": 2,
  "next_cursor": "eyJzIjoicmF0aW5nX2ltZGIiLCJkIjp0cnVlLCJ2IjoiOS40MCIsImlkIjoyMjA4MDF9",
  "total": null
}

Передавайте next_cursor в следующий запрос с теми же параметрами, пока он не станет null. Курсор работает в каталоге /titles и в витринах, которые на нём построены, — топе и скрытых жемчужинах. Остальные списки листаются offset, а на cursor отвечают 400.

С sort=random листать нельзя: у случайного порядка нет следующей страницы. cursor и offset с ним дают 400 — просто повторите запрос, чтобы получить новую выборку.

Разделы

Списки, элементы которых различаются по одному признаку, приходят разделами. Каждый раздел — сам список, с теми же полями и подписью на двух языках:

curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "limit=1" \
  --data-urlencode "fields=title" \
  "https://api.kinodata.space/v1.3/titles/kp/301/relations"

Ответ200

{
  "counts": {
    "reference": 86,
    "referenced_in": 672,
    "related": 9,
    "similar": 74
  },
  "has_more": false,
  "items": [
    {
      "has_more": true,
      "items": [
        {
          "imdb_id": "tt1375666",
          "kp_id": "447301",
          "tmdb_id": "27205",
          "tmdb_tv_id": null,
          "kinorium_id": "472809",
          "title_ru": "Начало",
          "title_en": "Inception"
        }
      ],
      "label_en": "Similar",
      "label_ru": "Похожие",
      "relation": "similar",
      "total": 74
    },
    {
      "has_more": true,
      "items": [
        {
          "imdb_id": "tt0366179",
          "kp_id": "63744",
          "tmdb_id": "24358",
          "tmdb_tv_id": null,
          "kinorium_id": null,
          "title_ru": "Аниматрица: Второе возрождение – Часть 1",
          "title_en": "The Second Renaissance Part I"
        }
      ],
      "label_en": "Related",
      "label_ru": "Связанные",
      "relation": "related",
      "total": 9
    },
    {
      "has_more": true,
      "items": [
        {
          "imdb_id": "tt1431045",
          "kp_id": "462360",
          "tmdb_id": "293660",
          "tmdb_tv_id": null,
          "kinorium_id": "485426",
          "title_ru": "Дэдпул",
          "title_en": "Deadpool"
        }
      ],
      "label_en": "Referenced in",
      "label_ru": "Упоминается в",
      "relation": "referenced_in",
      "total": 672
    },
    {
      "has_more": true,
      "items": [
        {
          "imdb_id": "tt0060196",
          "kp_id": "349",
          "tmdb_id": "429",
          "tmdb_tv_id": null,
          "kinorium_id": "56474",
          "title_ru": "Хороший, плохой, злой",
          "title_en": "The Good, the Bad and the Ugly"
        }
      ],
      "label_en": "References",
      "label_ru": "Отсылки к",
      "relation": "reference",
      "total": 86
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 4
}

список	разделы по умолчанию	другие варианты `group`
Состав `/titles/{type}/{id}/cast`	по роли: `role`	`none`
Тексты `/titles/{type}/{id}/texts`	по виду: `kind`	`none`
Связи `/titles/{type}/{id}/relations`	по связи: `relation`	`none`
Медиа `/titles/{type}/{id}/media`	без разделов	`type`, `class`, `language`
Фильмография `/persons/{type}/{id}/filmography`	без разделов	`role`
Серии `/titles/{type}/{id}/episodes`	без разделов	`season` — сводка по сезонам

limit в разделённом списке относится к каждому разделу, а total раздела — его настоящий размер. Чтобы получить плоский список, передайте group=none. Чтобы листать один раздел, сузьте список до него: role=actor, kind=fact, relation=similar.

Листать разделённый список нельзя: у разделов нет общей последовательности. offset без сужения даёт 400:

curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "limit=2" \
  --data-urlencode "offset=2" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/cast"

Ответ400

{
  "error": {
    "code": "invalid_request",
    "message": "grouped lists have no single sequence to page through — narrow to one value to page inside it, or ask for group=none",
    "field": "offset"
  }
}

Только нужные поля

Параметр fields оставляет в ответе то, что вы перечислили.

В карточке тайтла имена — блоки карточки: fields=title,ratings. Можно и наоборот, убрать лишнее: fields=-akas,-tags. Смешивать в одном параметре нельзя: fields=title,-akas даёт 400.
В списках имена — поля элемента списка: fields=title,year,rating_imdb или fields=-genres,-countries. title оставляет title_ru и title_en, poster_url — poster_url_ru и poster_url_en.

ID тайтла приходят всегда, даже если вы их не перечислили: без них элемент не с чем связать. Поля идут в том же порядке, что и без fields. Неизвестное имя — 400 со списком допустимых.

fields работает в карточке тайтла, во всех списках тайтлов — каталоге, подборке, связях, фильмографии, совместных работах, витринах и календаре — и в поиске людей. В составе, медиа, текстах и сериях его нет: там fields даёт 400.

Дальше

Фильтры и сортировка — как выбрать и упорядочить элементы.
Каталог и поиск — главный список API.

Списки и пагинация

Форма списка#

Когда total равен null#

Сколько элементов на странице#

Страницы: offset#

Глубокая прокрутка: cursor#

Разделы#

Только нужные поля#

Дальше#

Форма списка

Когда total равен null

Сколько элементов на странице

Страницы: offset

Глубокая прокрутка: cursor

Разделы

Только нужные поля

Дальше