Языки ответа

API отдаёт тексты на русском и английском. Язык каждого текстового поля указан в его имени, а параметр lang оставляет в ответе один язык.

Язык в имени поля#

Каждое текстовое поле заканчивается на _ru или _en: title_ru, kind_label_en, name_ru. Без lang приходят обе половины:

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

{
  "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"
  },
  "type": {
    "kind": "movie",
    "is_series": false,
    "status": "released",
    "kind_label_ru": "Фильм",
    "kind_label_en": "Movie",
    "status_label_ru": "Вышел",
    "status_label_en": "Released"
  }
}

Имена полей не меняются никогда: title_en — всегда английское название, в любом ответе и с любым lang. Разбирайте ответ по именам полей, а не по языку запроса.

Один язык: lang#

lang=ru оставляет поля _ru, lang=en — поля _en. Остальные поля ответа не меняются.

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

{
  "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"
  }
}

lang принимает только ru и en. Другое значение — ошибка 400. Передавать lang можно в любой запрос: там, где текстов нет (/ids, /meta/stats), он ничего не меняет.

Перевода нет — null#

Если текста на нужном языке нет, поле равно null. API не подставляет вместо него другой язык или оригинал: что показать, решаете вы. Для названия разумно взять title_original, для описания — текст на другом языке с пометкой.

Что не зависит от языка#

Поля без суффикса одинаковы на любом языке: ID, slug, kind, коды стран, даты, числа, title_original, названия компаний.

Суффикс _ru в фильтрах дат означает регион, а не язык: premiere_ru — премьера в России.

Что сейчас есть только на одном языке#

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

Факты с lang=en приходят без текста — так видно, что перевода ещё нет:

curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=fact" \
  --data-urlencode "limit=1" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/447301/texts"

{
  "counts": {
    "fact": 37,
    "faq": 16,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "fact_kind": "general",
      "is_spoiler": false,
      "kind": "fact",
      "ord": 0,
      "text_en": null
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 37
}

Когда перевод появится, он придёт в *_en, а ваш код менять не придётся.

Английские названия и постеры#

• title_en — только настоящее английское название. Оригинальное название неанглоязычного фильма или транслитерация туда не попадают: тогда title_en равно null, а название на языке оригинала лежит в title_original.
• poster_url_en — постер с надписями на английском. Если такого нет — null. poster_url_ru — постер для русской витрины.
• Ссылки на Кинориум с lang=en ведут на английскую версию сайта, en.kinorium.com.

Дальше#

• Списки и пагинация — как устроены все списки API.
• ID во всех каталогах — связка ID одного тайтла.