# Title card

> Everything about a movie or series in one request: titles, overviews, ratings, dates, awards, media and cast.

> Documentation index for agents: https://kinodata.space/en/llms.txt — the whole documentation in one file: https://kinodata.space/en/llms-full.txt

Request: `GET https://api.kinodata.space/v1.3/titles/{type}/{id}`

The card opens by an ID from any of the five catalogs: `/titles/kp/447301` and `/titles/imdb/tt1375666` return the same thing.

The full card has up to 22 blocks and is about 26 KB, about 8 KB compressed. If you need part of it, list the blocks in `fields`: the response gets smaller and easier to parse. The `ids` block always comes back.

## Path parameters

- `type` (string, required) — The catalog the ID comes from: IMDb, Kinopoisk, TMDB (movie or series) or Kinorium.
  Values: `imdb`, `kp`, `tmdb`, `tmdb_tv`, `kinorium`.
- `id` (string, required) — The ID in that catalog. IMDb IDs are `tt` followed by digits (`tt1375666`); the others are digits (`447301`).

## Query parameters

- `fields` (csv) — Which blocks to return: `fields=title,ratings`. With a `-` sign, which to drop: `fields=-akas,-tags`. The two can’t be mixed. All blocks by default.
  Values: `ids`, `meta`, `title`, `type`, `synopsis`, `release`, `ratings`, `finance`, `awards`, `countries`, `classification`, `series`, `media`, `genres`, `companies`, `akas`, `tags`, `watch`, `parental`, `credits_top`, `franchise`, `counts`.
  Example: `fields=title,ratings`.
- `lang` (ru | en) — Keep one language in the response. Without it, text fields come in `_ru` and `_en` pairs. More in [Response languages](https://kinodata.space/en/docs/languages.md).

## Response fields

- `ids` (object) — The title's IDs in every catalog and links to its pages. Always returned, even if it isn't in `fields`.
  - `imdb_id` (string | null) — IMDb ID.
  - `kp_id` (string | null) — Kinopoisk ID.
  - `tmdb_id` (string | null) — TMDB movie ID.
  - `tmdb_tv_id` (string | null) — TMDB series ID. At most one of `tmdb_id` and `tmdb_tv_id` is set.
  - `kinorium_id` (string | null) — Kinorium ID.
  - `urls` (object) — Links to the title’s pages: `imdb`, `kp`, `tmdb`, `kinorium`. With `lang=en` the Kinorium link points to `en.kinorium.com`.
- `meta` (object) — Service information about the card.
  - `updated_at` (string) — When the title’s data was last updated, ISO 8601 in UTC.
- `title` (object) — Titles.
  - `title_ru` (string | null) — Russian title.
  - `title_en` (string | null) — English title. Only a real one: the original title of a non-English film or a transliteration never goes here, and then it is `null`.
  - `title_original` (string | null) — Title in the original language.
- `type` (object) — Kind and status of the title.
  - `kind` (enum) — Kind of title.
    Values: `movie`, `series`, `mini_series`, `tv_show`, `anime`, `cartoon`, `short`.
  - `is_series` (boolean) — Whether the title has episodes.
  - `status` (enum) — Release status. Every value is in `/enums`, set `statuses`.
    Values: `released`, `ended`, `returning_series`, `in_production`, `post_production`, `in_development`, `planned`, `canceled`.
  - `kind_label_ru`, `kind_label_en` (string) — Kind label: «Фильм» / «Movie».
  - `status_label_ru`, `status_label_en` (string) — Status label: «Вышел» / «Released».
- `synopsis` (object) — Overviews and taglines. Each text comes from its own source rather than being a translation of the other.
  - `overview_ru`, `overview_en` (string | null) — Plot overview.
  - `short_overview_ru`, `short_overview_en` (string | null) — A one- or two-sentence overview.
  - `tagline_ru`, `tagline_en` (string | null) — Tagline.
  - `overview_alter_ru`, `overview_alter_en` (string | null) — A second overview from another source, when it differs from the first.
- `release` (object) — Year, runtime and release dates.
  - `year` (integer | null) — Release year.
  - `runtime` (integer | null) — Runtime in minutes.
  - `releases` (array) — Release dates by region. Each date appears once: if the US digital release matches the worldwide one, it is only under `world`.
    - `region` (string) — Region: `world` is the earliest date worldwide, `us` is the US, `ru` is Russia.
    - `dates` (array) — Dates in the region: `type` and `date`. Types: `premiere`, `release` for the theatrical release, `digital`; labels are in `/enums`, set `title_release_types`. Dates are `YYYY-MM-DD`.
- `ratings` (object) — Ratings by source. There is no overall score on purpose: sources have different scales and audiences.
  - `sources` (object) — Ratings by source: the key is the source (`imdb`, `kp`, `tmdb`, `kinorium`, `letterboxd`, `rt`, `metacritic`, `critics`, `cr`), the value has `value`, `votes`, `scale` (10 or 100), `kind: "critics"` for critics’ scores and the page `url`. Kinorium also has `distribution`: how many viewers gave each score from 1 to 10. Kinorium counts it separately, so its sum doesn’t match `votes`. Source labels are in `/enums`, set `rating_sources`. No source, no key.
  - `votes_total` (integer | null) — Kinopoisk, IMDb and TMDB votes combined.
  - `divergence_kp_imdb` (number | null) — How far the Kinopoisk and IMDb ratings are apart, as an absolute value.
  - `popularity` (number | null) — TMDB’s popularity index. It is not a vote count.
- `finance` (object) — Money, in US dollars.
  - `budget` (integer | null) — Budget.
  - `box_office_us` (integer | null) — US box office.
  - `revenue_world` (integer | null) — Worldwide box office.
- `awards` (object) — Awards: totals and a breakdown by ceremony.
  - `wins_imdb`, `nominations_imdb` (integer | null) — Wins and all nominations, including the won ones, according to IMDb, across every award worldwide.
  - `oscars_won`, `oscars_nominated` (integer | null) — Oscars: wins and all nominations, including the won ones.
  - `wins_ceremonies`, `nominations_ceremonies` (integer) — Wins and all nominations across the ceremonies in `ceremonies`.
  - `summary_kinorium_ru` (string | null) — Kinorium’s per-ceremony summary, in Russian.
  - `summary_imdb_en` (string | null) — IMDb’s summary: “Won 4 Oscars. 160 wins & 220 nominations total”. A different text, not a translation of Kinorium’s.
  - `ceremonies` (array) — Ceremonies by prestige, Oscars first.
    - `slug` (string | null) — Ceremony code: `oscar`, `bafta`, `golden_globe`…
    - `ceremony_ru`, `ceremony_en` (string) — Ceremony name.
    - `icon` (string | null) — Path to the ceremony icon on `api.kinodata.space`: gold for a win, grey for a nomination.
    - `won` (boolean) — Whether there is at least one win.
    - `wins`, `nominations` (integer) — Wins and all nominations, including the won ones.
    - `years` (array) — Ceremony years.
    - `items` (array) — Categories: `category_ru`, `category_en`, `won`, `year`.
- `countries` (array) — Production countries: `code` (ISO 3166-1, lowercase), `name_ru`, `name_en`.
- `classification` (object) — Age rating and language.
  - `age_limit` (integer | null) — Russian age rating: 0, 6, 12, 16 or 18.
  - `mpaa` (string | null) — US certificate: `G`, `PG`, `PG-13`, `R`, `NC-17` or `TV-*`.
  - `original_language` (string | null) — Original language, ISO 639-1.
  - `is_adult` (boolean) — Adult content.
- `series` (object) — Series data. All `null` for a movie.
  - `seasons_total`, `episodes_total` (integer | null) — Seasons and episodes.
  - `start_year`, `end_year` (integer | null) — Years on air. `end_year` is `null` for a running series.
- `media` (object) — Posters, backdrop, trailers and soundtrack. Other stills and videos are in `/titles/{type}/{id}/media`.
  - `poster_url_ru`, `poster_url_en` (string | null) — Poster for a Russian and an English storefront. The English one has English lettering; `null` if there is none.
  - `poster_source_ru`, `poster_source_en` (string | null) — Where the poster comes from: `kp`, `tmdb`, `imdb`, `kinorium`.
  - `posters_by_source` (object) — Each source’s poster: `kp`, `tmdb`, `imdb`, `kinorium`.
  - `backdrop_url` (string | null) — A wide still for a background.
  - `poster_animated` (string) — Kinorium’s animated poster: an mp4 clip of up to 7 MB. About one popular title in ten has it; when it’s missing, so is the key. Show it in `<video autoplay muted loop playsinline>` and load it on demand.
  - `trailers` (array) — Trailers: `url` and `youtube_id`, `language`, `runtime_sec`, `thumbnail_url`, `preview_url`, `kind` with labels. All videos are in `/media`.
  - `soundtrack` (object | null) — Soundtrack album: `name` and the Apple Music `url`.
- `genres` (array) — Genres: `slug`, `name_ru`, `name_en`.
- `companies` (array) — Companies: `name`, `slug` and the role `kind`: `production`, `studio`, `network`, `special_effects`, `distributor_theatrical`, `distributor_online`, `dubbing`.
- `akas` (array) — Alternative titles: `title`, `regions` (country codes), `source` and `language` when it is known.
- `tags` (array) — Kinorium tags: `kind` (`adjective` for mood, `keyword`, `subgenre`) with labels, `tag_ru`, `tag_en`.
- `watch` (array) — Where to watch and what to read, by ascending `rank`: `url`, `host` and the site `kind` with labels: streaming, ratings, official site, encyclopedia… Every kind is in `/enums`, set `site_kinds`.
- `parental` (array) — Parental guide by category: `category`, `severity` (`mild`, `moderate`, `severe`), labels and `source`.
- `credits_top` (array) — Directors and the leading cast, ready to display. The full cast is in `/titles/{type}/{id}/cast`.
  - `imdb_id` (string | null) — IMDb ID.
  - `kp_id` (string | null) — Kinopoisk ID.
  - `tmdb_id` (string | null) — TMDB person ID.
  - `kinorium_id` (string | null) — Kinorium ID.
  - `name_ru`, `name_en` (string | null) — Name.
  - `photo_url` (string | null) — Photo.
  - `role` (enum) — Role. Every value is in `/enums`, set `credit_roles`.
  - `role_label_ru`, `role_label_en` (string) — Role label: «Режиссёр» / «Director».
  - `character_ru`, `character_en` (string | null) — The character, for an actor.
- `franchise` (object) — Franchise: `name`, `poster_url` and `size`, the number of titles in it. Only titles in a franchise have this block. The franchise’s titles are in `/titles/{type}/{id}/relations?relation=related`.
- `counts` (object) — How much there is on the sub-resources: `cast`, `images`, `videos`, `facts`, `faq`, `quotes`, `episodes`, `seasons`, `relations`. Use them to decide what is worth a separate request.

## Errors

| status | code | when |
|---|---|---|
| 400 | `invalid_request` | Unknown `type`, an ID that doesn’t match the catalog format, an unknown block in `fields` or both `fields` modes mixed, `lang` other than `ru` or `en`; any other parameter (such as `limit`): the card takes only `fields` and `lang`. |
| 404 | `not_found` | No title found for this ID. |
| 401 | `unauthorized` | The `X-API-Key` header is missing, or the key is unknown or revoked. |
| 429 | `rate_limited` | The per-second rate limit or the daily quota is used up. |

Every code and what to do about it is on the [Errors](https://kinodata.space/en/docs/errors.md) page.

## Examples

### English only

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "fields=title,type,synopsis" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/447301"
```

Response `200`:

```json
{
  "ids": {
    "imdb_id": "tt1375666",
    "kp_id": "447301",
    "tmdb_id": "27205",
    "tmdb_tv_id": null,
    "kinorium_id": "472809",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt1375666/",
      "kinorium": "https://en.kinorium.com/472809/",
      "kp": "https://www.kinopoisk.ru/film/447301/",
      "tmdb": "https://www.themoviedb.org/movie/27205"
    }
  },
  "title": {
    "title_en": "Inception",
    "title_original": "Inception"
  },
  "type": {
    "kind": "movie",
    "is_series": false,
    "status": "released",
    "kind_label_en": "Movie",
    "status_label_en": "Released"
  },
  "synopsis": {
    "tagline_en": "Your mind is the scene of the crime.",
    "overview_en": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another person's idea into a target's subconscious.",
    "short_overview_en": "A thief who steals corporate secrets through the use of dream-sharing technology is given the inverse task of planting an idea into the mind of a CEO, but his tragic past may doom the project and his team to disaster.",
    "overview_alter_en": null
  }
}
```

### Titles and overview

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "fields=title,synopsis" \
  "https://api.kinodata.space/v1.3/titles/kp/447301"
```

Response `200`:

```json
{
  "ids": {
    "imdb_id": "tt1375666",
    "kp_id": "447301",
    "tmdb_id": "27205",
    "tmdb_tv_id": null,
    "kinorium_id": "472809",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt1375666/",
      "kinorium": "https://ru.kinorium.com/472809/",
      "kp": "https://www.kinopoisk.ru/film/447301/",
      "tmdb": "https://www.themoviedb.org/movie/27205"
    }
  },
  "title": {
    "title_ru": "Начало",
    "title_en": "Inception",
    "title_original": "Inception"
  },
  "synopsis": {
    "tagline_ru": "Твой разум – место преступления",
    "tagline_en": "Your mind is the scene of the crime.",
    "overview_ru": "Кобб — талантливый вор, лучший из лучших в опасном искусстве извлечения: он крадет ценные секреты из глубин подсознания во время сна, когда человеческий разум наиболее уязвим. Редкие способности Кобба сделали его ценным игроком в привычном к предательству мире промышленного шпионажа, но они же превратили его в извечного беглеца и лишили всего, что он когда-либо любил. И вот у Кобба появляется шанс исправить ошибки. Его последнее дело может вернуть все назад, но для этого ему нужно совершить невозможное — инициацию. Вместо идеальной кражи Кобб и его команда спецов должны будут провернуть обратное. Теперь их задача — не украсть идею, а внедрить ее. Если у них получится, это и станет идеальным преступлением. Но никакое планирование или мастерство не могут подготовить команду к встрече с опасным противником, который, кажется, предугадывает каждый их ход. Врагом, увидеть которого мог бы лишь Кобб.",
    "overview_en": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another person's idea into a target's subconscious.",
    "short_overview_en": "A thief who steals corporate secrets through the use of dream-sharing technology is given the inverse task of planting an idea into the mind of a CEO, but his tragic past may doom the project and his team to disaster.",
    "overview_alter_ru": "Мы привыкли, что в нашем понимании вор – это человек способный украсть какие-то ценности или деньги. Сюжет картины рассказывает о ворах, способных украсть идею прямо у человека из подсознания. Одним из таких является главный герой фильма Доминик Кобб. После того, как его жена умерла, он вынужден скрываться, и не может даже вернуться в страну, чтобы повидать детей. Как-то раз Кобб получает очень неординарный заказ: ему нужно не украсть, а наоборот внедрить новую идею в подсознание человека. Доминику не очень хочется браться за это дело, но заказчик в обмен предлагает возможность вернуться домой. Заручившись поддержкой профессионалов этого дела, Кобб начинает разрабатывать план, как все провернуть. Все нужно очень хорошо продумать, ведь ворам предстоит воссоздать многослойную реальность в подсознании объекта, в результате чего грани могут начать стираться.",
    "overview_alter_en": null,
    "short_overview_ru": "Профессиональные воры внедряются в сон наследника огромной империи. Фантастический боевик Кристофера Нолана"
  }
}
```

### Ratings

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "fields=ratings" \
  "https://api.kinodata.space/v1.3/titles/kp/447301"
```

Response `200`:

```json
{
  "ids": {
    "imdb_id": "tt1375666",
    "kp_id": "447301",
    "tmdb_id": "27205",
    "tmdb_tv_id": null,
    "kinorium_id": "472809",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt1375666/",
      "kinorium": "https://ru.kinorium.com/472809/",
      "kp": "https://www.kinopoisk.ru/film/447301/",
      "tmdb": "https://www.themoviedb.org/movie/27205"
    }
  },
  "ratings": {
    "sources": {
      "cr": {
        "value": 92,
        "votes": 13,
        "scale": 100
      },
      "critics": {
        "value": 8.4,
        "votes": 363,
        "scale": 10,
        "kind": "critics"
      },
      "imdb": {
        "value": 8.8,
        "votes": 2877173,
        "scale": 10,
        "url": "https://www.imdb.com/title/tt1375666/"
      },
      "kinorium": {
        "value": 8.6,
        "votes": 27048,
        "scale": 10,
        "url": "https://ru.kinorium.com/472809/",
        "distribution": [
          27,
          26,
          59,
          104,
          280,
          695,
          2003,
          4409,
          5332,
          5577
        ]
      },
      "kp": {
        "value": 8.7,
        "votes": 1132562,
        "scale": 10,
        "url": "https://www.kinopoisk.ru/film/447301/"
      },
      "letterboxd": {
        "value": 8.4,
        "votes": 3604328,
        "scale": 10
      },
      "metacritic": {
        "value": 74,
        "votes": 42,
        "scale": 100,
        "kind": "critics"
      },
      "rt": {
        "value": 86,
        "votes": 364,
        "scale": 100,
        "kind": "critics"
      },
      "tmdb": {
        "value": 8.4,
        "votes": 40402,
        "scale": 10,
        "url": "https://www.themoviedb.org/movie/27205"
      }
    },
    "votes_total": 4050137,
    "divergence_kp_imdb": 0.1,
    "popularity": 50.947
  }
}
```

### Series

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "fields=title,type,series" \
  "https://api.kinodata.space/v1.3/titles/tmdb_tv/1396"
```

Response `200`:

```json
{
  "ids": {
    "imdb_id": "tt0903747",
    "kp_id": "404900",
    "tmdb_id": null,
    "tmdb_tv_id": "1396",
    "kinorium_id": "400796",
    "urls": {
      "imdb": "https://www.imdb.com/title/tt0903747/",
      "kinorium": "https://ru.kinorium.com/400796/",
      "kp": "https://www.kinopoisk.ru/film/404900/",
      "tmdb": "https://www.themoviedb.org/tv/1396"
    }
  },
  "title": {
    "title_ru": "Во все тяжкие",
    "title_en": "Breaking Bad",
    "title_original": "Breaking Bad"
  },
  "type": {
    "kind": "series",
    "is_series": true,
    "status": "ended",
    "kind_label_ru": "Сериал",
    "kind_label_en": "TV series",
    "status_label_ru": "Завершён",
    "status_label_en": "Ended"
  },
  "series": {
    "seasons_total": 5,
    "episodes_total": 62,
    "start_year": 2008,
    "end_year": 2013
  }
}
```

### Unknown ID

```bash
curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/titles/kp/999999999"
```

Response `404`:

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