# Catalog and search

> Search titles by name and pick them from the whole database with filters.

> 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`

The main list in the API: search, storefronts and selections by any property. Filters, sorting and presets are covered in [Filters and sorting](https://kinodata.space/en/docs/filters.md); paging and `fields` in [Lists and pagination](https://kinodata.space/en/docs/lists.md).

Without `sort` the catalog goes by popularity, with titles that have no votes last. Pair sorting by a rating with a vote threshold: a handful of people can rate a title too.

## Query parameters

- `q` (string) — Search by title in any language. Forgives typos: “matrx” finds *The Matrix*. With `q` the default order is relevance.
  Example: `q=матрица`.
- `filters` — Any catalog filter with the `.any`, `.all`, `.not`, `.gte`, `.lte` operators: `kind=anime`, `country=jp`, `year.gte=1990`, `votes_imdb.gte=50000`, `person=kp:41477`. The full list is in [Filters and sorting](https://kinodata.space/en/docs/filters.md#what-you-can-filter).
- `sort` (string) — Order: a key with a sign, `-` for descending, `+` for ascending. Two keys are allowed: `sort=-rating_imdb,+year`. Popularity by default, relevance with `q`.
  Values: `popularity`, `relevance`, `release_date`, `year`, `runtime`, `rating`, `rating_imdb`, `rating_kp`, `rating_tmdb`, `rating_kr`, `rating_letterboxd`, `rating_rt`, `rating_metacritic`, `rating_critics`, `votes_imdb`, `votes_kp`, `votes_tmdb`, `votes_kr`, `votes_letterboxd`, `votes_total`, `rating_weighted`, `divergence`, `budget`, `box_office_us`, `revenue_world`, `wins_imdb`, `oscars_won`, `random`.
  Default: `popularity`, `relevance` with `q`. Example: `sort=-rating_imdb`.
- `preset` (enum) — A ready-made set of filters. Explicit parameters refine it. What each one holds is in [Filters and sorting](https://kinodata.space/en/docs/filters.md#ready-made-sets-preset).
  Values: `top`, `hidden_gems`, `trending`, `new`, `classics`.
  Example: `preset=top`.
- `limit` (integer) — Titles per page, from 1 to 50.
  Default: 50. Example: `limit=20`.
- `offset` (integer) — How many titles to skip from the start.
  Default: 0.
- `cursor` (string) — A cursor for deep paging. Send an empty `cursor=` first, then the `next_cursor` value from the response. Doesn’t work with `sort=random`. Only the catalog has it.
- `fields` (csv) — Which item fields to return: `fields=title,year`. With a `-` sign, which to drop: `fields=-genres`. `title` keeps `title_ru` and `title_en`, `poster_url` keeps `poster_url_ru` and `poster_url_en`. IDs always come back.
  Values: `title`, `title_original`, `year`, `release_date`, `kind`, `poster_url`, `posters_by_source`, `rating_kp`, `rating_tmdb`, `rating_imdb`, `rating_kr`, `rating_letterboxd`, `votes_kp`, `votes_tmdb`, `votes_imdb`, `countries`, `genres`.
  Example: `fields=title,year`.
- `lang` (ru | en) — Keep one language in the response.

## Response fields

- `items` (array) — Titles.
  - `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) — The catalog doesn’t count the total: an exact count of a filtered set is a second pass over the whole database. Page by `has_more`.
- `limit`, `offset` (integer) — Page size and offset. There is no `offset` when you page with a cursor.
- `has_more` (boolean) — Whether there is a next page.
- `next_cursor` (string | null) — The next page’s cursor, only if the request had `cursor`. `null` means there is nothing more.

## Errors

| status | code | when |
|---|---|---|
| 400 | `invalid_request` | An unknown filter, operator, `sort` key or `fields` name; a repeated parameter other than `person`; an unknown collection in `collection`; a parameter of another endpoint (such as `role` or `relation`); a non-numeric `limit`; `person.role` without `person`; `cursor` or `offset` with `sort=random`; a malformed cursor. |
| 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 "q=matrix" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_imdb" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_en": "The Matrix",
      "year": 1999,
      "rating_imdb": 8.7
    },
    {
      "imdb_id": "tt0234215",
      "kp_id": "299",
      "tmdb_id": "604",
      "tmdb_tv_id": null,
      "kinorium_id": "190315",
      "title_en": "The Matrix Reloaded",
      "year": 2003,
      "rating_imdb": 7.2
    },
    {
      "imdb_id": "tt0242653",
      "kp_id": "316",
      "tmdb_id": "605",
      "tmdb_tv_id": null,
      "kinorium_id": "196883",
      "title_en": "The Matrix Revolutions",
      "year": 2003,
      "rating_imdb": 6.7
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### With a typo

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "q=matrx" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_imdb" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_en": "The Matrix",
      "year": 1999,
      "rating_imdb": 8.7
    },
    {
      "imdb_id": "tt0234215",
      "kp_id": "299",
      "tmdb_id": "604",
      "tmdb_tv_id": null,
      "kinorium_id": "190315",
      "title_en": "The Matrix Reloaded",
      "year": 2003,
      "rating_imdb": 7.2
    },
    {
      "imdb_id": "tt0242653",
      "kp_id": "316",
      "tmdb_id": "605",
      "tmdb_tv_id": null,
      "kinorium_id": "196883",
      "title_en": "The Matrix Revolutions",
      "year": 2003,
      "rating_imdb": 6.7
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### Filters

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=anime" \
  --data-urlencode "country=jp" \
  --data-urlencode "votes_imdb.gte=50000" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_imdb" \
  "https://api.kinodata.space/v1.3/titles"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt2560140",
      "kp_id": "749374",
      "tmdb_id": null,
      "tmdb_tv_id": "1429",
      "kinorium_id": "678289",
      "title_ru": "Атака титанов",
      "title_en": "Attack on Titan",
      "year": 2013,
      "rating_imdb": 9.1
    },
    {
      "imdb_id": "tt1355642",
      "kp_id": "452838",
      "tmdb_id": null,
      "tmdb_tv_id": "31911",
      "kinorium_id": "468024",
      "title_ru": "Стальной алхимик: Братство",
      "title_en": "Fullmetal Alchemist: Brotherhood",
      "year": 2009,
      "rating_imdb": 9.1
    },
    {
      "imdb_id": "tt14986406",
      "kp_id": "4789626",
      "tmdb_id": null,
      "tmdb_tv_id": "326913",
      "kinorium_id": "2794509",
      "title_ru": "Блич: Тысячелетняя кровавая война",
      "title_en": "Bleach: Thousand-Year Blood War",
      "year": 2022,
      "rating_imdb": 9
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### A director’s films

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "person=kp:41477" \
  --data-urlencode "person.role=director" \
  --data-urlencode "released=true" \
  --data-urlencode "sort=-year" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year" \
  "https://api.kinodata.space/v1.3/titles"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt33764258",
      "kp_id": "6385370",
      "tmdb_id": "1368337",
      "tmdb_tv_id": null,
      "kinorium_id": "11772913",
      "title_ru": "Одиссея",
      "title_en": "The Odyssey",
      "year": 2026
    },
    {
      "imdb_id": "tt15398776",
      "kp_id": "4664634",
      "tmdb_id": "872585",
      "tmdb_tv_id": null,
      "kinorium_id": "2828885",
      "title_ru": "Оппенгеймер",
      "title_en": "Oppenheimer",
      "year": 2023
    },
    {
      "imdb_id": "tt6723592",
      "kp_id": "1236063",
      "tmdb_id": "577922",
      "tmdb_tv_id": null,
      "kinorium_id": "2023303",
      "title_ru": "Довод",
      "title_en": "Tenet",
      "year": 2020
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### Cursor

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "limit=2" \
  --data-urlencode "fields=title,rating_imdb" \
  --data-urlencode "cursor=" \
  "https://api.kinodata.space/v1.3/titles"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0903747",
      "kp_id": "404900",
      "tmdb_id": null,
      "tmdb_tv_id": "1396",
      "kinorium_id": "400796",
      "title_ru": "Во все тяжкие",
      "title_en": "Breaking Bad",
      "rating_imdb": 9.5
    },
    {
      "imdb_id": "tt5491994",
      "kp_id": "1007472",
      "tmdb_id": null,
      "tmdb_tv_id": "68595",
      "kinorium_id": "1605088",
      "title_ru": "Планета Земля 2",
      "title_en": "Planet Earth II",
      "rating_imdb": 9.4
    }
  ],
  "limit": 2,
  "next_cursor": "eyJzIjoicmF0aW5nX2ltZGIiLCJkIjp0cnVlLCJ2IjoiOS40MCIsImlkIjoyMjA4MDF9",
  "total": null
}
```

### Unknown filter

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

Response `400`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "unknown query parameter \"status\"",
    "field": "status",
    "hint": "there is no status filter; the card carries type.status, the catalog filters by released"
  }
}
```