---
name: z87:movies
description: 360K+ movies with 40-axis taste profiles, cast, themes, ratings, and soundtrack data. Taste-vector search for mood-based discovery, collaborative similarity, and side-by-side comparison.
---

Anonymous: 600 tok/min. Key: `GET https://z87.ai/api/use` → `X-Api-Key` header, 6000 tok/min. On `429`, wait 1s.

Start with /stats to see available genres, decades, languages, and all 40 taste axes.

## Search

Field-qualified BM25 search. Fields: title, director, cast, genre, keyword, language, decade, theme.

/search?q=title:inception — by title
/search?q=genre:horror language:en — English horror
/search?q=director:nolan genre:sci-fi — Nolan sci-fi
/search?q=cast:dicaprio decade:2010s — DiCaprio in the 2010s
/search?q=keyword:time travel — by keyword
/search?q=theme:redemption genre:drama — themed search

Numeric filters: min_rating, max_rating (TMDB 0-10), min_year, max_year, min_votes.
/search?q=genre:drama&min_rating=8.0&min_year=2000

## Taste-based discovery (/vibe)

Find movies by mood using 40 taste axes. Each axis is 0.0-1.0.

/vibe?q=cerebral:0.8+dark:0.7+tension:0.9 — brainy thrillers
/vibe?q=feel_good:0.9+humor:0.8 — feel-good comedies
/vibe?q=dark:0.9+psychological:0.8+mystery:0.7 — dark psych mysteries
/vibe?q=romantic:0.8+emotional_depth:0.9+tragic:0.7 — tragic love stories
/vibe?q=action_intensity:0.9+escapism:0.9+humor:0.0 — serious action
/vibe?q=family_friendly:0.9+humor:0.7+feel_good:0.8 — family movie night

Combine with filters: /vibe?q=cerebral:0.8&genre=thriller&min_rating=7.0&pool=popular

All 40 axes: cerebral, emotional_depth, dark, humor, tension, action_intensity, visual_style,
dialogue_driven, pacing_speed, complexity, realism, violence, sexual_content, family_friendly,
nostalgia, cultural_specificity, political, philosophical, romantic, supernatural, mystery,
character_development, ensemble_cast, anti_hero, redemption_arc, coming_of_age,
social_commentary, experimental, feel_good, tragic, inspirational, escapism, world_building,
musical, documentary_feel, psychological, body_horror, cosmic_horror, satire, meta_narrative.

## Similar movies

/similar/{id} — movies with similar taste profiles.
Returns shared_taste showing which axes both movies score high on.
Optional: genre, decade, pool, min_rating, limit.

## Recommendations

/recommend?movies=inception,interstellar — by name.
/recommend?movie_ids=0,1 — by ID.
/recommend?like=inception&dislike=transformers — refine with dislikes.

Modes: similar (default), opposite, explore.
Pools: popular (default), known, deep, obscure.
Filters: genre, decade, min_rating.

## Compare

/compare?ids=42,87 — side-by-side taste profiles, similarity score, shared genres.

## Other

/suggest?q=inc — autocomplete titles.
/details/{id} — full movie detail with cast, themes, taste profile, soundtrack.
/random — random movie (accepts genre, pool, decade, min_rating).

All endpoints accept both **GET with query parameters** and **POST with JSON body**.

## Endpoints

### `https://z87.ai/api/movies/search`

Field-qualified search. Fields: title, director, cast, genre, keyword, language, decade, theme. Numeric: min_rating, max_rating, min_year, max_year, min_votes

| Param | Type | Required | Default |
|-------|------|----------|---------|
| q | string | no | — |
| min_rating | f32 | no | — |
| min_year | u16 | no | — |
| max_year | u16 | no | — |
| min_votes | u32 | no | — |
| limit | u32 | no | 20 |
| offset | u32 | no | 0 |

**Example:** `GET https://z87.ai/api/movies/search?q=title:inception&limit=1`

**Response:**
```json
{
  "movies": [
    {
      "id": 19,
      "title": "Inception",
      "year": 2010,
      "genres": ["Action", "...2 more"],
      "directors": [],
      "tmdb_rating": 8.4,
      "imdb_rating": 8.8,
      "runtime_minutes": 148
    }
  ],
  "total": 2,
  "limit": 1,
  "offset": 0
}
```

### `https://z87.ai/api/movies/vibe`

Taste-vector discovery. Query by mood using 40 axes (0.0-1.0): cerebral, dark, humor, tension, romantic, feel_good, etc. Filters: genre, decade, language, min_rating, pool

| Param | Type | Required | Default |
|-------|------|----------|---------|
| q | string | **yes** | — |
| genre | string | no | — |
| decade | string | no | — |
| language | string | no | — |
| min_rating | f32 | no | — |
| pool | string | no | popular |
| limit | u32 | no | 20 |

**Example:** `GET https://z87.ai/api/movies/vibe?q=cerebral:0.8+dark:0.7+tension:0.9&limit=5`

**Response:**
```json
{
  "movies": [
    {
      "id": 35748,
      "title": "Pop",
      "year": 2018,
      "genres": [],
      "directors": ["Caden Douglas"],
      "tmdb_rating": 8.0,
      "poster_url": "",
      "score": 0.523
    },
    "...4 more"
  ],
  "query": {"cerebral": 0.8, "dark": 0.7, "tension": 0.9},
  "pool": "popular"
}
```

### `https://z87.ai/api/movies/similar/{id}`

Find movies with similar taste profiles. Returns shared_taste axes explaining the match

| Param | Type | Required | Default |
|-------|------|----------|---------|
| genre | string | no | — |
| pool | string | no | popular |
| min_rating | f32 | no | — |
| limit | u32 | no | 20 |

**Example:** `GET https://z87.ai/api/movies/similar/0?limit=3`

**Response:**
```json
{
  "movie": {
    "id": 0,
    "title": "War Machine",
    "year": 2026,
    "genres": ["Action", "...2 more"],
    "directors": ["Patrick Hughes"],
    "tmdb_rating": 7.26,
    "imdb_rating": 6.4,
    "runtime_minutes": 110
  },
  "similar": [
    {
      "id": 675,
      "title": "Elevation",
      "year": 2024,
      "genres": ["Action", "...2 more"],
      "directors": ["George Nolfi"],
      "tmdb_rating": 6.43,
      "poster_url": "https://image.tmdb.org/t/p/w500/tnfc0NJ3BzhJrGJhkkEd6MHBdq5.jpg",
      "score": 0.979
    },
    "...2 more"
  ]
}
```

### `https://z87.ai/api/movies/recommend`

Multi-movie recommendations. Pass names (movies, like, dislike) or IDs (movie_ids, like_ids, dislike_ids). Modes: similar, opposite, explore. Pools: popular, known, deep, obscure

| Param | Type | Required | Default |
|-------|------|----------|---------|
| movies | string | no | — |
| movie_ids | string | no | — |
| like | string | no | — |
| like_ids | string | no | — |
| dislike | string | no | — |
| dislike_ids | string | no | — |
| mode | string | no | similar |
| pool | string | no | popular |
| genre | string | no | — |
| decade | string | no | — |
| min_rating | f32 | no | — |
| limit | u32 | no | 20 |

**Example:** `GET https://z87.ai/api/movies/recommend?movies=inception,interstellar&limit=5`

**Response:**
```json
{
  "suggestions": [
    {
      "id": 17955,
      "title": "Inside 'Interstellar'",
      "year": 2015,
      "genres": ["Documentary"],
      "directors": ["Jordan Goldberg", "...1 more"],
      "tmdb_rating": 6.82,
      "poster_url": "https://image.tmdb.org/t/p/w500/xWA7Bbo9VeahPcKCFYiC7NZXNoV.jpg",
      "score": 0.98
    },
    "...4 more"
  ],
  "like": [{"id": 19, "title": "Inception"}, "...1 more"],
  "mode": "similar",
  "pool": "popular",
  "limit": 5
}
```

### `https://z87.ai/api/movies/compare`

Side-by-side taste profile comparison with similarity score and shared genres

| Param | Type | Required | Default |
|-------|------|----------|---------|
| ids | string | **yes** | — |

**Example:** `GET https://z87.ai/api/movies/compare?ids=0,1`

**Response:**
```json
{
  "movies": [
    {
      "id": 0,
      "title": "War Machine",
      "year": 2026,
      "genres": ["Action", "...2 more"],
      "directors": ["Patrick Hughes"],
      "tmdb_rating": 7.26,
      "imdb_rating": 6.4,
      "runtime_minutes": 110
    },
    {
      "id": 1,
      "title": "Shelter",
      "year": 2026,
      "genres": ["Action", "...2 more"],
      "directors": ["Ric Roman Waugh"],
      "tmdb_rating": 6.56,
      "imdb_rating": 6.2,
      "runtime_minutes": 108
    }
  ],
  "taste_comparison": {
    "cerebral": [0.4, "...1 more"],
    "emotional_depth": [0.6, "...1 more"],
    "dark": [0.7, "...1 more"],
    "tension": [0.8, "...1 more"],
    "action_intensity": [0.9, "...1 more"],
    "visual_style": [0.6, "...1 more"],
    "dialogue_driven": [0.3, "...1 more"],
    "pacing_speed": [0.8, "...1 more"],
    "complexity": [0.4, "...1 more"],
    "realism": [0.3, "...1 more"],
    "violence": [0.8, "...1 more"],
    "cultural_specificity": [0.4, "...1 more"],
    "political": [0.3, "...1 more"],
    "philosophical": [0.3, "...1 more"],
    "supernatural": [0.8, "...1 more"],
    "mystery": [0.5, "...1 more"],
    "character_development": [0.5, "...1 more"],
    "ensemble_cast": [0.7, "...1 more"],
    "anti_hero": [0.6, "...1 more"],
    "redemption_arc": [0.7, "...1 more"],
    "social_commentary": [0.3, "...1 more"],
    "feel_good": [0.2, "...1 more"],
    "tragic": [0.6, "...1 more"],
    "inspirational": [0.5, "...1 more"],
    "escapism": [0.8, "...1 more"],
    "world_building": [0.6, "...1 more"],
    "musical": [0.4, "...1 more"],
    "documentary_feel": [0.3, "...1 more"],
    "psychological": [0.6, "...1 more"],
    "body_horror": [0.4, "...1 more"],
    "cosmic_horror": [0.5, "...1 more"]
  },
  "shared_genres": ["Action", "Thriller"],
  "similarity_score": 0.933
}
```

### `https://z87.ai/api/movies/suggest`

Autocomplete movie titles by prefix

| Param | Type | Required | Default |
|-------|------|----------|---------|
| q | string | **yes** | — |
| limit | u32 | no | 20 |

**Example:** `GET https://z87.ai/api/movies/suggest?q=incep&limit=5`

**Response:**
```json
{"movies": [{"id": 19, "name": "Inception"}, "...1 more"]}
```

### `https://z87.ai/api/movies/details/{id}`

Full movie detail — cast, themes, taste profile, soundtrack, trailers, posters

No parameters.

**Example:** `GET https://z87.ai/api/movies/details/0`

**Response:**
```json
{
  "movie": {
    "id": 0,
    "title": "War Machine",
    "year": 2026,
    "synopsis": "...ion during Army Ranger training, a combat engineer must lead his unit in a fight against a giant oth...",
    "tagline": "All grit. No quit.",
    "runtime_minutes": 110,
    "original_language": "en",
    "poster_url": "https://image.tmdb.org/t/p/w500/tlPgDzwIE7VYYIIAGCTUOnN4wI1.jpg",
    "backdrop_url": "https://image.tmdb.org/t/p/w1280/6yeVcxFR0j08vlv2OlL6zbewm4D.jpg",
    "tmdb_rating": 7.26,
    "tmdb_vote_count": 1009,
    "imdb_rating": 6.4,
    "popularity_score": 361.661,
    "genres": ["Action", "...2 more"],
    "keywords": ["military sci-fi", "...2 more"],
    "directors": ["Patrick Hughes"],
    "cast": [
      {
        "name": "Alan Ritchson",
        "character": "81",
        "photo_url": "https://image.tmdb.org/t/p/w185/92YNEEpCyugkTzPprJwZpvVtvuK.jpg"
      },
      "...9 more"
    ],
    "themes": [{"theme": "Military Camaraderie", "relevance_score": 0.9}, "...4 more"],
    "taste_profile": {
      "cerebral": 0.4,
      "emotional_depth": 0.6,
      "dark": 0.7,
      "humor": 0.1,
      "tension": 0.8,
      "action_intensity": 0.9,
      "visual_style": 0.6,
      "dialogue_driven": 0.3
    },
    "tmdb_id": 1265609,
    "trailer_url": "https://www.youtube.com/watch?v=AFuE1LRxm80",
    "imdb_id": "tt15940132",
    "soundtrack_profile": {
      "importance": 0.6,
      "original_score_quality": 0.7,
      "licensed_songs_prominence": 0.2,
      "music_drives_narrative": false,
      "notable_details": "...sounds to mirror the mechanical threat of the machines, punctuated by somber, atmospheric strings du..."
    }
  }
}
```

### `https://z87.ai/api/movies/random`

Random movie. Filters: genre, pool, decade, min_rating

| Param | Type | Required | Default |
|-------|------|----------|---------|
| genre | string | no | — |
| pool | string | no | — |
| decade | string | no | — |
| min_rating | f32 | no | — |

**Example:** `GET https://z87.ai/api/movies/random`

**Response:**
```json
{
  "movie": {
    "id": 225705,
    "title": "Raato Ghar",
    "year": 2017,
    "synopsis": "...war) and Kartikey (Sanyam Puri) and shows their crime drama unconventionally. It is a social drama m...",
    "tagline": "Action, Comedy",
    "runtime_minutes": 138,
    "original_language": "en",
    "poster_url": "https://image.tmdb.org/t/p/w500/jSwAsFFKlYdC7oQJrcNwimWOGoB.jpg"
  }
}
```

### `https://z87.ai/api/movies/stats`

Dataset statistics — genre, decade, language, theme distributions and all 40 taste axes

No parameters.

**Example:** `GET https://z87.ai/api/movies/stats`

**Response:**
```json
{
  "total": 351260,
  "fields": {
    "genre": [
      ["drama", 132078],
      ["comedy", 77074],
      ["documentary", 64630],
      ["romance", 32035],
      ["thriller", 24290],
      ["animation", 23884],
      ["crime", 21283],
      ["action", 21133],
      ["tv movie", 19302],
      ["horror", 18746],
      ["family", 15484],
      ["music", 15399],
      ["adventure", 13482],
      ["fantasy", 11758],
      ["history", 10839],
      ["mystery", 10612],
      ["science fiction", 9685],
      ["war", 6828],
      ["western", 5147]
    ],
    "language": [
      ["en", 170293],
      ["fr", 21577],
      ["es", 19541],
      ["de", 18085],
      ["ja", 12174],
      ["it", 9334],
      ["ru", 9092],
      ["pt", 7555],
      ["zh", 6052],
      ["hi", 5138],
      ["tr", 3998],
      ["sv", 3509],
      ["nl", 3419],
      ["ar", 3112],
      ["ko", 3111],
      ["cs", 3033],
      ["pl", 3006],
      ["cn", 2620],
      ["ta", 2610],
      ["tl", 2533],
      ["el", 2432],
      ["ml", 2399],
      ["da", 2279],
      ["te", 2104],
      ["bn", 2065],
      ["hu", 2016],
      ["fi", 1969],
      ["fa", 1779],
      ["id", 1628],
      ["no", 1407],
      ["xx", 1316],
      ["ro", 1295],
      ["he", 1226],
      ["sh", 1226],
      ["kn", 1217],
      ["uk", 1111],
      ["th", 880],
      ["sr", 857],
      ["mr", 764],
      ["bg", 720],
      ["ka", 662],
      ["hr", 632],
      ["et", 612],
      ["pa", 532],
      ["sk", 522],
      ["ms", 521],
      ["ca", 497],
      ["sl", 492],
      ["lv", 476],
      ["lt", 461],
      "...107 more"
    ],
    "decade": [
      ["2010s", 98594],
      ["2020s", 61474],
      ["2000s", 49322],
      ["1990s", 28252],
      ["1980s", 24292],
      ["1970s", 21518],
      ["1960s", 18433],
      ["1950s", 13024],
      ["1930s", 10864],
      ["1940s", 10109],
      ["1920s", 4934],
      ["1910s", 3461],
      ["1900s", 901],
      ["1890s", 367],
      ["1880s", 6],
      ["1870s", 2]
    ],
    "theme": [
      ["isolation", 16275],
      ["coming of age", 14598],
      ["family dynamics", 11130],
      ["survival", 11036],
      ["friendship", 10223],
      ["grief and loss", 9679],
      ["betrayal", 8193],
      ["moral ambiguity", 8079],
      ["redemption", 7661],
      ["cultural identity", 7308],
      ["self-discovery", 7111],
      ["loss of innocence", 6938],
      ["revenge", 6464],
      ["human connection", 6314],
      ["obsession", 6054],
      ["resilience", 5599],
      ["slapstick comedy", 5409],
      ["fatalism", 5167],
      ["deception", 5136],
      ["sacrifice", 4534],
      ["personal growth", 4514],
      ["generational conflict", 4106],
      ["existential dread", 4087],
      ["social alienation", 3721],
      ["greed", 3488],
      ["unrequited love", 3281],
      ["family secrets", 3223],
      ["forbidden love", 3219],
      ["justice", 3061],
      ["perseverance", 3048],
      ["surrealism", 3038],
      ["social inequality", 2967],
      ["interpersonal relationships", 2916],
      ["heroism", 2831],
      ["urban alienation", 2822],
      ["paranoia", 2803],
      ["childhood innocence", 2802],
      ["identity", 2801],
      ["friendship and loyalty", 2800],
      ["moral decay", 2749],
      ["historical memory", 2738],
      ["adventure", 2715],
      ["power dynamics", 2640],
      ["family reconciliation", 2620],
      ["mortality", 2506],
      ["existentialism", 2494],
      ["political corruption", 2446],
      ["social isolation", 2424],
      ["social stigma", 2424],
      ["family bonds", 2406],
      "...50 more"
    ],
    "keyword": [
      ["short film", 15352],
      ["woman director", 10713],
      ["based on novel or book", 5458],
      ["lgbt", 4014],
      ["gay theme", 3367],
      ["biography", 3256],
      ["murder", 3170],
      ["based on true story", 2291],
      ["musical", 2281],
      ["christmas", 2217],
      ["silent film", 2173],
      ["world war ii", 1904],
      ["coming of age", 1866],
      ["sports", 1814],
      ["love", 1731],
      ["anime", 1714],
      ["revenge", 1592],
      ["family", 1572],
      ["black and white", 1550],
      ["friendship", 1466],
      ["new york city", 1362],
      ["romance", 1293],
      ["based on play or musical", 1249],
      ["martial arts", 1239],
      ["sequel", 1119],
      ["philippines", 1059],
      ["found footage", 975],
      ["police", 968],
      ["dark comedy", 894],
      ["japan", 892],
      ["high school", 885],
      ["holiday", 878],
      ["ghost", 871],
      ["politics", 868],
      ["remake", 867],
      ["serial killer", 861],
      ["kidnapping", 849],
      ["concert", 805],
      ["parent child relationship", 798],
      ["prison", 798],
      ["death", 791],
      ["suicide", 784],
      ["pre-code", 762],
      ["superhero", 760],
      ["documentary", 758],
      ["dog", 748],
      ["based on manga", 744],
      ["paris, france", 741],
      ["detective", 740],
      ["stop motion", 733],
      "...50 more"
    ]
  },
  "taste_axes": [
    "cerebral",
    "emotional_depth",
    "dark",
    "humor",
    "tension",
    "action_intensity",
    "visual_style",
    "dialogue_driven",
    "pacing_speed",
    "complexity",
    "realism",
    "violence",
    "sexual_content",
    "family_friendly",
    "nostalgia",
    "cultural_specificity",
    "political",
    "philosophical",
    "romantic",
    "supernatural",
    "mystery",
    "character_development",
    "ensemble_cast",
    "anti_hero",
    "redemption_arc",
    "coming_of_age",
    "social_commentary",
    "experimental",
    "feel_good",
    "tragic",
    "inspirational",
    "escapism",
    "world_building",
    "musical",
    "documentary_feel",
    "psychological",
    "body_horror",
    "cosmic_horror",
    "satire",
    "meta_narrative"
  ],
  "pools": ["popular", "known", "deep", "obscure"]
}
```

## License

The z87 API code is MIT licensed. Each dataset carries its upstream license:
- **movies**: Movie metadata sourced from TMDB (CC BY-NC 4.0). Taste profiles, themes, and soundtrack analysis are AI-generated. z87 API code is MIT.


---

## Other z87 Datasets

- [chess](https://z87.ai/api/chess/SKILL.md) — 1B+ Lichess games (2000+ Elo, 2013-2026)
- [colors](https://z87.ai/api/colors/SKILL.md) — Unified paint color database: ~30K colors across 20+ brands with cross-brand matching via CIEDE2000 perceptual distance, color harmony generation, coordinating color strips, and palette suggestions.
- [companies_uk](https://z87.ai/api/companies_uk/SKILL.md) — 5.7M UK companies from Companies House
- [countries](https://z87.ai/api/countries/SKILL.md) — 247 countries with 282 indicators (57 static, 225 timeseries) across economics, health, demographics, energy, environment, education, and more
- [design](https://z87.ai/api/design/SKILL.md) — 1,003 production-grade frontend designs with HTML, screenshots, prompts, and structured metadata (26 categories, 40 styles, 4K+ tags)
- [food](https://z87.ai/api/food/SKILL.md) — Recipes, FDC ingredients, and food products: 13.5K recipes with nutrition, 8K+ FDC ingredients, curated products with Nutri-Score and NOVA ratings.
- [gbif](https://z87.ai/api/gbif/SKILL.md) — GBIF Backbone Taxonomy: 7.7 million taxa with full taxonomic hierarchy, synonym resolution, tree navigation, and full-text search across the tree of life.
- [gutenberg](https://z87.ai/api/gutenberg/SKILL.md) — 60,000 Project Gutenberg books with chapter-level access, BM25 full-text search, cover art, illustrations, and AI-generated tags (genre, mood, era, locations, five-word summaries).
- [holidays](https://z87.ai/api/holidays/SKILL.md) — 3,391 public holidays across 121 countries (2026–2027)
- [home](https://z87.ai/api/home/SKILL.md) — Unified smart home device database
- [jokes](https://z87.ai/api/jokes/SKILL.md) — 41,000 jokes from three sources, AI-tagged with category, rating, topics, and offensive score
- [manpages](https://z87.ai/api/manpages/SKILL.md) — 142K Linux man pages with AI-generated cheat cards, category tags, use-frequency scores, and plain-english descriptions
- [mtg](https://z87.ai/api/mtg/SKILL.md) — 29K Magic: The Gathering cards with synergy graph engine, combo detection, and Commander deck builder.
- [music](https://z87.ai/api/music/SKILL.md) — 651K artists, 500K+ albums, 1M+ songs from MusicBrainz with genre, country, and member data
- [osm](https://z87.ai/api/osm/SKILL.md) — 46M+ OpenStreetMap POIs with Hilbert-curve spatial index and BM25 text search
- [podcast](https://z87.ai/api/podcast/SKILL.md) — 1M+ podcasts from PodcastIndex with categories, language, episode counts, popularity scores, and cadence estimates
- [restaurants](https://z87.ai/api/restaurants/SKILL.md) — 10K London restaurants with menus, Michelin stars, ingredient category scores (seafood, meat, game, etc.), and capacity data
- [solve](https://z87.ai/api/solve/SKILL.md) — Computation engine: symbolic algebra, statistics, regression, finance, graph algorithms, Monte Carlo simulation
- [wikipedia](https://z87.ai/api/wikipedia/SKILL.md) — 7.2 million English Wikipedia articles with full markdown content, infoboxes, inter-article links, and geographic coordinates.
- [wiktionary](https://z87.ai/api/wiktionary/SKILL.md) — 8M+ Wiktionary entries across 4,000+ languages

Full index: [https://z87.ai/api/SKILL.md](https://z87.ai/api/SKILL.md)