Response languages

The API serves text in Russian and English. The language of every text field is in its name, and the lang parameter keeps just one language in the response.

The language is in the field name#

Every text field ends in _ru or _en: title_ru, kind_label_en, name_ru. Without lang you get both halves:

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

Field names never change: title_en is always the English title, in every response and with any lang. Read the response by field name, not by the language you asked for.

One language: lang#

lang=en keeps the _en fields, lang=ru keeps the _ru fields. Everything else in the response stays the same.

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 accepts only ru and en. Any other value returns 400. You can send lang with any request: where a response has no text (/ids, /meta/stats), it changes nothing.

No translation means null#

When there is no text in the requested language, the field is null. The API never falls back to another language or the original: what to show instead is your call. For a title, title_original is a sensible choice; for an overview, the text in the other language with a note.

What doesn't depend on language#

Fields without a suffix are the same in every language: IDs, slug, kind, country codes, dates, numbers, title_original, company names.

In date filters the _ru suffix means the region, not the language: premiere_ru is the premiere in Russia.

What is in one language only today#

Both languages cover titles, overviews, genres, countries, mood tags and keywords, award ceremonies and categories, collections and the labels of every enum. Still in one language:

With lang=en, facts come back without text, which shows the translation isn't there yet:

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
}

When a translation arrives it lands in *_en, and your code doesn't need to change.

English titles and posters#

• title_en holds only a real English title. The original title of a non-English film or a transliteration never goes there: in that case title_en is null and the original-language title is in title_original.
• poster_url_en is a poster with English lettering; null if there is none. poster_url_ru is the poster for a Russian storefront.
• With lang=en, Kinorium links point to the English site, en.kinorium.com.

Next#

• Lists and pagination: how every list in the API works.
• IDs in every catalog: one title's linked IDs.