Люди¶

Пути с {type}/{id} принимают imdb · kp · tmdb · kinorium и номер человека в этом каталоге.

`GET /persons`¶

Ищет человека по имени — на русском, английском или в оригинальном написании.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`q`	строка	да	—	имя или его часть; достаточно фамилии
`limit`	целое	нет	50	размер страницы, максимум 50
`offset`	целое	нет	0	смещение

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/persons?q=нолан&limit=1"

Ответ¶

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "nm0634240",
      "kp_id": "41477",
      "tmdb_id": "525",
      "name_ru": "Кристофер Нолан",
      "name_en": "Christopher Nolan",
      "name_orig": null,
      "birth_year": 1970,
      "death_year": null,
      "gender": "male",
      "birthplace": "Westminster, London, England, UK",
      "photo_url": "https://image.tmdb.org/t/p/original/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
      "professions": ["actor", "cinematographer", "composer", "director", "editor", "producer", "writer"],
      "biography": "Sir Christopher Edward Nolan (born 30 July 1970) is a British and American filmmaker. …",
      "popularity": 5.470699787139893,
      "also_known_as": ["Christopher Edward Nolan", "Chris Nolan", "Sir Christopher Nolan"],
      "homepage": null,
      "instagram": null,
      "kinorium_id": "476400"
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": null
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	нечисловой `limit` или `offset`
`401`	`unauthorized`	ключ отсутствует или недействителен

Примечания¶

Поиск идёт по фамилии, а не только по началу полного имени: спилберг находит Стивена Спилберга. Опечатки прощаются — dikaprio находит Леонардо ДиКаприо. Точные совпадения стоят выше, внутри них порядок задаёт известность.

Человек собран из нескольких каталогов в одну запись, поэтому часть внешних номеров бывает null: у Джонатана Нолана есть kp_id и tmdb_id, но нет imdb_id.

total здесь всегда null — поиск не считает выборку, он ранжирует и отдаёт верх. Листайте по has_more.

Биография и список альтернативных написаний в примере выше сокращены; в ответе они полные.

`GET /persons/{type}/{id}`¶

Профиль человека со сводкой по ролям и самыми заметными работами.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`type`	путь	да	—	`imdb` · `kp` · `tmdb` · `kinorium`
`id`	путь	да	—	номер человека в этом каталоге

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/persons/tmdb/525"

Ответ¶

{
  "person": {
    "imdb_id": "nm0634240",
    "kp_id": "41477",
    "tmdb_id": "525",
    "name_ru": "Кристофер Нолан",
    "name_en": "Christopher Nolan",
    "name_orig": null,
    "birth_year": 1970,
    "death_year": null,
    "gender": "male",
    "birthplace": "Westminster, London, England, UK",
    "photo_url": "https://image.tmdb.org/t/p/original/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
    "professions": ["actor", "cinematographer", "composer", "director", "editor", "producer", "writer"],
    "biography": "Sir Christopher Edward Nolan (born 30 July 1970) is a British and American filmmaker. …",
    "popularity": 5.470699787139893,
    "also_known_as": ["Christopher Edward Nolan", "Chris Nolan", "Sir Christopher Nolan"],
    "homepage": null,
    "instagram": null,
    "kinorium_id": "476400"
  },
  "credits_summary": [
    { "role": "actor",           "count": 103 },
    { "role": "producer",        "count": 22 },
    { "role": "writer",          "count": 20 },
    { "role": "director",        "count": 19 },
    { "role": "editor",          "count": 5 },
    { "role": "cinematographer", "count": 5 },
    { "role": "crew",            "count": 3 },
    { "role": "composer",        "count": 1 }
  ],
  "known_for": [
    {
      "imdb_id": "tt0468569",
      "kp_id": "111543",
      "tmdb_id": "155",
      "tmdb_tv_id": null,
      "title_ru": "Тёмный рыцарь",
      "title_en": "The Dark Knight",
      "title_original": "The Dark Knight",
      "year": 2008,
      "release_date": "2008-07-14",
      "kind": "movie",
      "poster_kp": "https://avatars.mds.yandex.net/get-kinopoisk-image/1599028/0fa5bf50-d5ad-446f-a599-b26d070c8b99/600x900",
      "poster_tmdb": "https://image.tmdb.org/t/p/original/aPtN76OjnNKLqCJ2FJBnQOIL031.jpg",
      "poster_imdb": null,
      "rating_kp": 8.5,
      "rating_tmdb": 8.5,
      "rating_imdb": 9.1,
      "votes_kp": 814734,
      "votes_tmdb": 36668,
      "votes_imdb": 3224733,
      "countries": [
        { "code": "us", "name_ru": "США", "name_en": "United States" },
        { "code": "gb", "name_ru": "Великобритания", "name_en": "United Kingdom" }
      ],
      "genres": ["action", "crime", "speculative_fiction", "thriller"],
      "rating_kr": 8.6,
      "rating_letterboxd": 9.0,
      "kinorium_id": "352641"
    }
  ]
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестный `type`
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	такого номера человека нет в базе

Примечания¶

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

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

Известность (popularity) считается по вниманию к странице человека, а не по кассе или наградам.

`GET /persons/{type}/{id}/filmography`¶

Тайтлы, в которых человек участвовал, — по одной карточке на тайтл со всеми его ролями в ней.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`role`	строка	нет	все	оставить тайтлы, где у человека есть эта роль
`group`	строка	нет	плоский список	`role` — секции по ролям; `none` — плоский
`sort`	строка	нет	`-release_date`	ключ со знаком, как в каталоге
`lang`	строка	нет	`ru`	язык производного `title` и имён персонажей
`fields`	CSV	нет	вся карточка	выбор ключей; доступен и `credits`
`limit`	целое	нет	1000	размер страницы или секции
`offset`	целое	нет	0	смещение; с секциями отвечает `400`

Плюс вся фильтрация каталога: ?genre=, ?year.gte=, ?rating_imdb.gte=.

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/persons/tmdb/525/filmography?role=director&sort=-rating_imdb&limit=1"

Ответ¶

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0468569",
      "kp_id": "111543",
      "tmdb_id": "155",
      "tmdb_tv_id": null,
      "title_ru": "Тёмный рыцарь",
      "title_en": "The Dark Knight",
      "title_original": "The Dark Knight",
      "year": 2008,
      "release_date": "2008-07-14",
      "kind": "movie",
      "poster_kp": "https://avatars.mds.yandex.net/get-kinopoisk-image/1599028/0fa5bf50-d5ad-446f-a599-b26d070c8b99/600x900",
      "poster_tmdb": "https://image.tmdb.org/t/p/original/aPtN76OjnNKLqCJ2FJBnQOIL031.jpg",
      "poster_imdb": null,
      "rating_kp": 8.5,
      "rating_tmdb": 8.5,
      "rating_imdb": 9.1,
      "votes_kp": 814734,
      "votes_tmdb": 36668,
      "votes_imdb": 3224733,
      "countries": [
        { "code": "us", "name_ru": "США", "name_en": "United States" },
        { "code": "gb", "name_ru": "Великобритания", "name_en": "United Kingdom" }
      ],
      "genres": ["action", "crime", "speculative_fiction", "thriller"],
      "rating_kr": 8.6,
      "rating_letterboxd": 9.0,
      "kinorium_id": "352641",
      "title": "Тёмный рыцарь",
      "poster_url": "https://avatars.mds.yandex.net/get-kinopoisk-image/1599028/0fa5bf50-d5ad-446f-a599-b26d070c8b99/600x900",
      "credits": [
        { "role": "director", "character": null, "character_ru": null, "character_en": null, "job": null, "ord": 0 },
        { "role": "writer",   "character": null, "character_ru": null, "character_en": null, "job": "Screenplay", "ord": 7 },
        { "role": "producer", "character": null, "character_ru": null, "character_en": null, "job": null, "ord": 1 }
      ]
    }
  ],
  "limit": 1,
  "offset": 0,
  "roles": [
    { "count": 19,  "label": "Режиссёры",        "role": "director" },
    { "count": 103, "label": "Актёры",           "role": "actor" },
    { "count": 20,  "label": "Сценаристы",       "role": "writer" },
    { "count": 22,  "label": "Продюсеры",        "role": "producer" },
    { "count": 5,   "label": "Операторы",        "role": "cinematographer" },
    { "count": 1,   "label": "Композиторы",      "role": "composer" },
    { "count": 5,   "label": "Монтажёры",        "role": "editor" },
    { "count": 3,   "label": "Съёмочная группа", "role": "crew" }
  ],
  "total": 19
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестная `role`, ключ сортировки, `group` или `lang`; `offset` с секциями
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	такого номера человека нет в базе

Примечания¶

Тайтл появляется один раз, а все роли человека в нём собраны в credits: режиссёр-сценарист-продюсер — это одна карточка с тремя кредитами, а не три строки.

roles считает по всей фильмографии, даже когда задан ?role= — иначе из открытой вкладки некуда было бы вернуться. total при этом считает выдачу: 19 режиссёрских работ при 103 актёрских в roles.

Элемент credits — та же форма, что в составе тайтла, поэтому «кто что делал» рисуется одним компонентом с обеих сторон.

`GET /persons/{type}/{id}/with/{type2}/{id2}`¶

Тайтлы, над которыми работали оба человека.

Параметры¶

имя	тип	обязательный	по умолчанию	описание
`type` / `id`	путь	да	—	первый человек
`type2` / `id2`	путь	да	—	второй человек
`role`	строка	нет	любая	оба в этой роли: со-актёры, со-режиссёры
`sort`	строка	нет	новые сверху	`rating` — по оценке
`limit`	целое	нет	1000	размер страницы
`offset`	целое	нет	0	смещение

Запрос¶

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.2/persons/tmdb/525/with/tmdb/6193?sort=rating&limit=1"

Ответ¶

{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt1375666",
      "kp_id": "447301",
      "tmdb_id": "27205",
      "tmdb_tv_id": null,
      "title_ru": "Начало",
      "title_en": "Inception",
      "title_original": "Inception",
      "year": 2010,
      "release_date": "2010-07-08",
      "kind": "movie",
      "poster_kp": "https://avatars.mds.yandex.net/get-kinopoisk-image/1629390/8ab9a119-dd74-44f0-baec-0629797483d7/600x900",
      "poster_tmdb": "https://image.tmdb.org/t/p/original/piQXcdOGgv1O9HQ07pI0tnjkGJw.jpg",
      "poster_imdb": null,
      "rating_kp": 8.7,
      "rating_tmdb": 8.4,
      "rating_imdb": 8.8,
      "votes_kp": 1127148,
      "votes_tmdb": 40155,
      "votes_imdb": 2866853,
      "countries": [
        { "code": "us", "name_ru": "США", "name_en": "United States" },
        { "code": "gb", "name_ru": "Великобритания", "name_en": "United Kingdom" }
      ],
      "genres": ["action", "drama", "mystery", "speculative_fiction", "thriller"],
      "rating_kr": 8.6,
      "rating_letterboxd": 8.4,
      "kinorium_id": "472809"
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 20
}

Ошибки¶

статус	код	когда
`400`	`invalid_request`	неизвестный `type` или `type2`
`401`	`unauthorized`	ключ отсутствует или недействителен
`404`	`not_found`	одного из номеров нет в базе

Примечания¶

Без role совпадение считается по любому участию: режиссёр и его постоянный оператор попадут в список так же, как два актёра. Поэтому среди двадцати общих работ Нолана и ДиКаприо есть и церемонии, где оба были в кадре. ?role=actor оставляет только те тайтлы, где оба сыграли.

Сортировка здесь своя, короткая: по умолчанию новые сверху, ?sort=rating — по оценке. Знаковая грамматика каталога сюда не распространяется.

Люди¶

GET /persons¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /persons/{type}/{id}¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /persons/{type}/{id}/filmography¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

GET /persons/{type}/{id}/with/{type2}/{id2}¶

Параметры¶

Запрос¶

Ответ¶

Ошибки¶

Примечания¶

`GET /persons`¶

`GET /persons/{type}/{id}`¶

`GET /persons/{type}/{id}/filmography`¶

`GET /persons/{type}/{id}/with/{type2}/{id2}`¶