Документация API фильмов
Кинобаза API отдаёт данные о фильмах и сериалах в JSON. Все запросы делаются методом GET на адрес
https://api.cinemapi.ru, тексты приходят в UTF-8.
- Получите ключ. Укажите почту на главной, ключ придёт письмом.
- Отправьте запрос. Передайте ключ в заголовке
X-API-Key. - Разберите ответ. Если данных нет, поле приходит как
null, пустой список как[].
Тестовые запросы на этой странице уходят на сервер ниже с вашим ключом. Ключ хранится только в этом браузере.
Авторизация
Каждый запрос должен содержать ключ в заголовке X-API-Key. Без ключа или с неверным ключом API ответит
кодом 401. Не публикуйте ключ в коде сайта или приложения, который видят пользователи: делайте запросы со своего сервера.
curl "https://api.cinemapi.ru/v1/films/258687" \
-H "X-API-Key: $KINOBAZA_KEY"Ответы и ошибки
Успешный ответ приходит с кодом 200. При ошибке приходит объект error с машинным кодом и описанием на русском:
{
"error": {
"code": "not_found",
"message": "Фильма с ID 1 нет в базе"
}
}| HTTP | code | Когда |
|---|---|---|
| 400 | bad_request | Неверный параметр: не тот тип, значение вне диапазона, неизвестный жанр или страна |
| 401 | unauthorized | Нет ключа или ключ неверный |
| 404 | not_found | Фильма с таким ID нет в базе или адрес метода неверный |
| 429 | rate_limited | Превышен лимит запросов, см. Лимиты |
| 503 | unavailable | База временно недоступна, повторите запрос позже |
Постраничная выдача
Поиск и фильтры возвращают список частями. Параметры page (с 1) и limit (от 1 до 100,
по умолчанию 20) выбирают страницу. В ответе кроме items есть номер страницы, размер, общее число
найденных фильмов и число страниц:
{ "items": [ … ], "page": 1, "limit": 20, "total": 1773, "pages": 89 }Лимиты
Бесплатный ключ: 500 запросов в сутки и 5 запросов в секунду. Суточный лимит обнуляется в полночь по Москве. При
превышении API отвечает кодом 429, а заголовок Retry-After говорит, через сколько секунд повторить
запрос. Лимиты платных тарифов указаны на странице тарифов.
В каждом ответе есть заголовки X-RateLimit-Limit с суточным лимитом ключа и
X-RateLimit-Remaining с числом запросов, оставшихся до полуночи.
GET/v1/films/{id}
Фильм или сериал по ID Кинопоиска. Ответ: объект фильма.
| Параметр | Тип | Описание |
|---|---|---|
id обязательный | integer, в пути | ID фильма на Кинопоиске, например 258687 |
GET/v1/films/search
Поиск по русскому или оригинальному названию, регистр не важен. Сначала идут фильмы с наибольшим числом голосов на Кинопоиске. Ответ: список объектов фильма.
| Параметр | Тип | Описание |
|---|---|---|
query обязательный | string | Часть названия, от 2 до 200 символов |
page | integer | Номер страницы, по умолчанию 1 |
limit | integer | Фильмов на странице, от 1 до 100, по умолчанию 20 |
GET/v1/films
Список фильмов и сериалов с фильтрами и сортировкой. Все параметры необязательные, их можно сочетать. Ответ: список объектов фильма.
| Параметр | Тип | Описание |
|---|---|---|
genre | string | Жанр из справочника, регистр не важен |
country | string | Страна из справочника |
type | string | movie — фильмы, series — сериалы |
year_from, year_to | integer | Год выхода от и до, включительно |
rating_from | number | Минимальная оценка Кинопоиска, от 0 до 10 |
votes_from | integer | Минимальное число голосов на Кинопоиске. Полезно вместе с сортировкой по оценке |
order | string | votes — популярные первыми (по умолчанию), rating — по оценке Кинопоиска, year — новые первыми, -year — старые первыми, name — по названию. В сортировках votes и rating участвуют только фильмы с оценкой Кинопоиска |
page, limit | integer | Страница и размер, см. Постраничная выдача |
GET/v1/genres
Все жанры и число фильмов в каждом, самые частые первыми. Эти названия принимает параметр genre.
GET/v1/countries
Все страны и число фильмов из каждой. Эти названия принимает параметр country.
GET/v1/stats
Сколько в базе фильмов и сериалов и у скольких из них заполнено каждое поле. Поле coverage поможет
заранее понять, на какие данные можно рассчитывать. Значения обновляются раз в 10 минут.
GET/v1/films/{id}/persons
Актёры и съёмочная группа фильма. В actors актёры по порядку титров с ролью в character, в
crew режиссёры, сценаристы, продюсеры и другие с кодом профессии в profession, как в
фильмографии. У каждого есть id, name, original_name и
photo. Если полный состав фильма ещё не загружен, люди берутся из фильмографий, и тогда порядок актёров
приблизительный.
GET/v1/persons/{id}
Актёр, режиссёр или другой участник по ID Кинопоиска. Ответ: объект персоны с полем
facts: список фактов о человеке.
GET/v1/persons/search
Поиск по имени на русском или в оригинале, регистр не важен. Сначала идут известные люди: те, у чьих фильмов больше всего голосов на Кинопоиске. Ответ: список объектов персоны без фактов.
| Параметр | Тип | Описание |
|---|---|---|
query обязательный | string | Часть имени, от 2 до 200 символов |
page, limit | integer | Страница и размер, см. Постраничная выдача |
GET/v1/persons/{id}/films
Фильмография, сначала новые фильмы. Если человек участвовал в фильме в нескольких ролях, например режиссёр и
сценарист, фильм приходит отдельной строкой на каждую. Ответ: список с полями
film_id, name, original_name, year, type,
profession (код), role (подпись на русском, например «Актер: играет самого себя») и
character (роль актёра).
| Параметр | Тип | Описание |
|---|---|---|
id обязательный | integer, в пути | ID персоны на Кинопоиске |
profession | string | actor, voice_actor, director, writer,
producer, composer, operator, editor, designer, voice_director,
translator, sound, production_manager или other |
page, limit | integer | Страница и размер, по умолчанию 50 на странице |
Объект фильма
Одинаковый во всех методах. Все поля присутствуют всегда, отсутствующие данные приходят как null.
| Поле | Тип | Описание |
|---|---|---|
id | integer | ID на Кинопоиске |
imdb_id | string | null | ID на IMDb, например tt0816692 |
type | string | movie или series |
name | string | null | Название на русском |
original_name | string | null | Оригинальное название |
year | integer | null | Год выхода, у сериала год начала |
duration | integer | null | Продолжительность в минутах |
age_rating | string | null | Возрастной рейтинг, например 18+ |
genres | string[] | Жанры |
countries | string[] | Страны производства |
short_description | string | null | Короткое описание в одно-два предложения |
description | string | null | Полное описание |
ratings | object | Оценки из разных источников, см. Оценки |
poster | object | null | url — постер в полном размере, preview_url — уменьшенный, около 300×450 |
Объект персоны
Все поля присутствуют всегда, отсутствующие данные приходят как null.
| Поле | Тип | Описание |
|---|---|---|
id | integer | ID на Кинопоиске |
name | string | null | Имя на русском |
original_name | string | null | Имя в оригинале |
sex | string | null | male или female |
birth_date, death_date | string | null | Дата в формате ГГГГ-ММ-ДД |
birth_place, death_place | string | null | Место рождения и смерти |
height | integer | null | Рост в сантиметрах |
professions | string[] | Профессии, например «Актер», «Режиссер» |
films_count | integer | null | Сколько разных фильмов в фильмографии |
photo | object | null | url — фото. У многих людей фото на Кинопоиске нет, тогда null |
Оценки
Каждая оценка — объект {"value", "votes"} или null, если её нет. Ключи в ratings есть всегда.
| Ключ | value | votes |
|---|---|---|
kinopoisk | Оценка Кинопоиска, от 0 до 10 | Число голосов |
imdb | Оценка IMDb, от 0 до 10 | Число голосов |
critics | Оценка мировых критиков, от 0 до 10 | Число рецензий |
russian_critics | Доля положительных рецензий российских критиков, % | Число рецензий |
positive_reviews | Доля положительных зрительских рецензий, % | Число рецензий |