# Введение

> Что умеет kinodata API, базовый адрес и формат ответов.

> Оглавление документации для агентов: https://kinodata.space/ru/llms.txt — вся документация одним файлом: https://kinodata.space/ru/llms-full.txt

kinodata связывает ID фильмов и сериалов в IMDb, Кинопоиске, TMDB и Кинориуме. По этой связке API отдаёт данные тайтла: названия на русском и английском, рейтинги каждого источника, состав, кадры и трейлеры, связи между тайтлами, фильмографии и подборки.

## Один фильм — пять ID

У «Начала» в каждом каталоге свой ID, и сами числа не говорят, что это один фильм:

| каталог | тип в пути | ID |
|---|---|---|
| IMDb | `imdb` | `tt1375666` |
| Кинопоиск | `kp` | `447301` |
| TMDB, фильмы | `tmdb` | `27205` |
| TMDB, сериалы | `tmdb_tv` | — |
| Кинориум | `kinorium` | `472809` |

Любой ID открывает тот же тайтл: `/titles/imdb/tt1375666`, `/titles/kp/447301` и `/titles/tmdb/27205` возвращают одинаковую карточку. Берите тот ID, который уже есть в вашей базе.

## Базовый адрес

```text
https://api.kinodata.space/v1.3
```

Пути в справочнике указаны от него: `/ids/kp/447301` — это `https://api.kinodata.space/v1.3/ids/kp/447301`. Все запросы — `GET` по HTTPS, ключ передаётся в заголовке `X-API-Key`.

## Формат ответа

JSON в UTF-8. Успешный ответ — сами данные, без обёртки. Ошибка — объект `error` и статус 4xx или 5xx:

```json
{ "error": { "code": "not_found", "message": "title not found: kp 999999999" } }
```

Успех от ошибки отличайте по статусу HTTP, а не по форме тела. Подробно — на странице [Ошибки](https://kinodata.space/ru/docs/errors.md).

## Языки

Текстовые поля приходят парами: `title_ru` и `title_en`, `name_ru` и `name_en`. Язык всегда виден из имени поля.

Параметр `lang=ru` или `lang=en` оставляет в ответе один язык, имена полей при этом не меняются. Если перевода нет, поле равно `null`: подставить другой язык или оригинальное название решаете вы.

## Ключ — только на сервере

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

## Дальше

- [Быстрый старт](https://kinodata.space/ru/docs/quickstart.md) — первый запрос за пять минут.
- [Языки ответа](https://kinodata.space/ru/docs/languages.md) — как устроены поля `_ru` и `_en`.
- [ID во всех каталогах](https://kinodata.space/ru/docs/ids.md) — самый простой эндпоинт.