# Hidden gems > Highly rated movies and series not that many people know about. > 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/discover/hidden-gems` Gems are the catalog with the `hidden_gems` preset: `/titles?preset=hidden_gems` gives the same response. A gem has 1,000–50,000 Kinopoisk votes and 1,000–25,000 IMDb votes: people rated it seriously, but few know it. Shorts, TV shows, concerts, stand-up, stage recordings (the `theatre` genre), music and documentaries are left out. Gems go by `rating_weighted`: the average of the Kinopoisk, IMDb and TMDB ratings, weighted by vote count. By default the top holds many series, Asian ones among them; `kind=movie` gives films: *The Day of the Doctor*, *Who’s Singin’ Over There?*, *The Marathon Family*, *Pretty Village, Pretty Flame*. Everything the catalog understands works here: filters, `q`, `sort`, `fields` and the cursor. ## Query parameters - `filters, q and sort` — Everything the [catalog](https://kinodata.space/en/docs/titles.md) understands: filters, the `q` search, `sort` with a sign, `fields` and the `cursor`. Details in [Filters and sorting](https://kinodata.space/en/docs/filters.md). Example: `kind=movie&country=fr`. - `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). Example: `lang=en`. - `limit` (integer) — How many titles to return, a whole number from 1 to 50. Default: 50. Example: `limit=20`. - `offset` (integer) — How many titles to skip, a whole number from 0. Default: 0. ## Response fields - `items` (array) — Titles: the same card as in the [catalog](https://kinodata.space/en/docs/titles.md). - `imdb_id`, `kp_id`, `tmdb_id`, `tmdb_tv_id`, `kinorium_id` (string | null) — The title’s catalog IDs. Always returned, even with `fields`. - `title_ru`, `title_en`, `title_original` (string | null) — Titles: Russian, English and in the original language. - `year` (integer | null) — Release year. - `release_date` (string | null) — First release date, `YYYY-MM-DD`. - `kind` (enum) — Kind of title: `movie`, `series`, `mini_series`, `tv_show`, `anime`, `cartoon`, `short`. - `poster_url_ru`, `poster_url_en` (string | null) — Poster for a Russian and an English storefront. - `posters_by_source` (object) — Each source’s poster: `kp`, `tmdb`, `imdb`, `kinorium`. - `rating_kp`, `rating_tmdb`, `rating_imdb`, `rating_kr`, `rating_letterboxd` (number | null) — Kinopoisk, TMDB, IMDb, Kinorium and Letterboxd ratings, 0–10 scale. - `votes_kp`, `votes_tmdb`, `votes_imdb` (integer | null) — Kinopoisk, TMDB and IMDb votes. - `countries` (array) — Countries: `code`, `name_ru`, `name_en`. - `genres` (array) — Genres: `slug`, `name_ru`, `name_en`. - `total` (null) — As in the catalog: the total isn’t counted. Page by `has_more` or with the cursor. - `limit`, `offset`, `has_more`, `next_cursor` — Paging, as in the [catalog](https://kinodata.space/en/docs/titles.md). ## Errors | status | code | when | |---|---|---| | 400 | `invalid_request` | Everything that returns `400` in the catalog, plus a `preset` of your own: this feed already is `preset=hidden_gems`. | | 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 "kind=movie" \ --data-urlencode "limit=4" \ --data-urlencode "fields=title,year,rating_kp,rating_imdb,votes_kp,votes_imdb" \ --data-urlencode "lang=en" \ "https://api.kinodata.space/v1.3/discover/hidden-gems" ``` Response `200`: ```json { "has_more": true, "items": [ { "imdb_id": "tt2779318", "kp_id": "807086", "tmdb_id": "313106", "tmdb_tv_id": null, "kinorium_id": "742468", "title_en": "The Day of the Doctor", "year": 2013, "rating_kp": 8.1, "rating_imdb": 9.3, "votes_kp": 20240, "votes_imdb": 21122 }, { "imdb_id": "tt0076276", "kp_id": "56709", "tmdb_id": "17909", "tmdb_tv_id": null, "kinorium_id": "70591", "title_en": "Who's Singin' Over There?", "year": 1980, "rating_kp": 7.7, "rating_imdb": 8.7, "votes_kp": 1028, "votes_imdb": 18000 }, { "imdb_id": "tt0084302", "kp_id": "84473", "tmdb_id": "29450", "tmdb_tv_id": null, "kinorium_id": "77675", "title_en": "The Marathon Family", "year": 1982, "rating_kp": 7, "rating_imdb": 8.8, "votes_kp": 2127, "votes_imdb": 18202 }, { "imdb_id": "tt0116860", "kp_id": "70816", "tmdb_id": "29927", "tmdb_tv_id": null, "kinorium_id": "106040", "title_en": "Pretty Village, Pretty Flame", "year": 1996, "rating_kp": 7.7, "rating_imdb": 8.6, "votes_kp": 2954, "votes_imdb": 19026 } ], "limit": 4, "offset": 0, "total": null } ``` ### Both languages ```bash curl -G -H "X-API-Key: $KINODATA_KEY" \ --data-urlencode "kind=movie" \ --data-urlencode "limit=4" \ --data-urlencode "fields=title,year,rating_kp,rating_imdb,votes_kp,votes_imdb" \ "https://api.kinodata.space/v1.3/discover/hidden-gems" ``` Response `200`: ```json { "has_more": true, "items": [ { "imdb_id": "tt2779318", "kp_id": "807086", "tmdb_id": "313106", "tmdb_tv_id": null, "kinorium_id": "742468", "title_ru": "День Доктора", "title_en": "The Day of the Doctor", "year": 2013, "rating_kp": 8.1, "rating_imdb": 9.3, "votes_kp": 20240, "votes_imdb": 21122 }, { "imdb_id": "tt0076276", "kp_id": "56709", "tmdb_id": "17909", "tmdb_tv_id": null, "kinorium_id": "70591", "title_ru": "Кто там поёт", "title_en": "Who's Singin' Over There?", "year": 1980, "rating_kp": 7.7, "rating_imdb": 8.7, "votes_kp": 1028, "votes_imdb": 18000 }, { "imdb_id": "tt0084302", "kp_id": "84473", "tmdb_id": "29450", "tmdb_tv_id": null, "kinorium_id": "77675", "title_ru": "Марафонцы бегут круг почета", "title_en": "The Marathon Family", "year": 1982, "rating_kp": 7, "rating_imdb": 8.8, "votes_kp": 2127, "votes_imdb": 18202 }, { "imdb_id": "tt0116860", "kp_id": "70816", "tmdb_id": "29927", "tmdb_tv_id": null, "kinorium_id": "106040", "title_ru": "Красивые деревни красиво горят", "title_en": "Pretty Village, Pretty Flame", "year": 1996, "rating_kp": 7.7, "rating_imdb": 8.6, "votes_kp": 2954, "votes_imdb": 19026 } ], "limit": 4, "offset": 0, "total": null } ``` ### No filters ```bash curl -G -H "X-API-Key: $KINODATA_KEY" \ --data-urlencode "limit=3" \ --data-urlencode "fields=title,year,kind,rating_kp,rating_imdb" \ "https://api.kinodata.space/v1.3/discover/hidden-gems" ``` Response `200`: ```json { "has_more": true, "items": [ { "imdb_id": "tt18224728", "kp_id": "4860668", "tmdb_id": null, "tmdb_tv_id": "157242", "kinorium_id": "8540771", "title_ru": "Святой Паисий: От Фарасы на небеса", "title_en": "Saint Paisios: From Farasa to Heaven", "year": 2022, "kind": "series", "rating_kp": 9.4, "rating_imdb": 8.9 }, { "imdb_id": "tt0809488", "kp_id": "260992", "tmdb_id": null, "tmdb_tv_id": "39651", "kinorium_id": "382558", "title_ru": "Крестный отец: Новелла для телевидения", "title_en": "The Godfather: A Novel for Television", "year": 1977, "kind": "series", "rating_kp": 8.7, "rating_imdb": 9.5 }, { "imdb_id": "tt5182866", "kp_id": "944829", "tmdb_id": null, "tmdb_tv_id": "64010", "kinorium_id": "1448428", "title_ru": "Вернуться в 1988", "title_en": "Reply 1988", "year": 2015, "kind": "series", "rating_kp": 8.9, "rating_imdb": 9 } ], "limit": 3, "offset": 0, "total": null } ```