Docs/APIs/Movie Lookup

Movie Lookup

Film Details, Cast, Crew and Ratings for 450,000 Movies

OperationalCredits 1 per callp50 284msEntertainmentStar

Overview

Pass `title`, `imdb` or `id`. A title search ignores case, accents, punctuation and a leading The, A or An, and also matches alternative titles; results come best-known first, `year` narrows them to that year (or one either side), and `limit` (paid) returns up to 10. `imdb` accepts a tt id or an IMDb title URL. No match returns 404.

Film data comes from Wikidata (CC0) and is refreshed monthly. Cast and crew lists are ordered best-known first. `releaseDate` is the earliest dated release anywhere; it is null when only the year is recorded. `boxOfficeUsd` is the largest US-dollar gross on record, which is normally the worldwide total. `contentRating` is the US MPA rating.

`scores` are computed by APIVerve. `rating` (0-100) starts from the critical and audience reception on record for the film and moves at most five points for its acclaim and popularity; it is null when no reception is on record, and `confidence` is high, medium or low by how much reception data there is. `acclaim` ranks the film's awards and nominations, weighted by prestige, against every film in the catalog. `popularity` ranks how widely the film is covered worldwide and, for films with an English Wikipedia article, its readership over the last full month. Both are percentiles, so 90 means more than 90% of films.

Live Test Movie Lookup API →

Endpoint

One host, one path per API. The block below shows this call in four languages; every one of them is the same HTTP request. Making requests covers the timeouts, retries and parameter rules that apply to all of them. The SDKs wrap the same call in a typed client.

GEThttps://api.apiverve.com/v1/movielookup
curl "https://api.apiverve.com/v1/movielookup?title=Inception&year=2010&imdb=tt1375666&id=Q25188&limit=5&cast=true" \
  -H "x-api-key: your_api_key_here"

Replace your_api_key_here with the key from your dashboard. When the inputs arrive as a list rather than one at a time, batch requests run up to 200 of them through this same API in a single call.

Authentication

Send your key in the x-api-key header. That is the only auth step — there is no token exchange and no per-endpoint scope to configure. Authentication covers creating, rotating and revoking keys.

401 is the only auth verdict

A 401 means the key is missing, invalid or expired. A 403 means the key is valid but not permitted here — blocked by a key restriction or an IP allow-list. Running out of credits is a 429.

Parameters

Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them.

ParameterTypeDescription
titleOptionalstringFilm title to search, e.g. Inception. Use title, imdb or id
length 0–200
yearOptionalintegerRelease year, to pick one of several films with the same title
range 1870–2100
imdbOptionalstringIMDb title id (tt1375666) or IMDb title URL
length 0–80
idOptionalstringWikidata id, e.g. Q25188
length 0–12
limitOptionalPremiumintegerMaximum films to return for a title search (1-10)
default 1 · range 1–10
castOptionalPremiumbooleanReturn the full cast instead of the top 5

Response

Every API returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape. Response format covers the envelope, the other output formats and how premium fields are withheld.

Sample response
{
  "status": "ok",
  "error": null,
  "data": {
    "query": "Inception",
    "count": 1,
    "movies": [
      {
        "title": "Inception",
        "originalTitle": "Inception",
        "year": 2010,
        "releaseDate": "2010-07-08",
        "type": "film",
        "runtimeMinutes": 148,
        "description": "2010 film directed by Christopher Nolan",
        "genres": [
          "drama",
          "action",
          "adventure",
          "science fiction",
          "heist",
          "mystery",
          "thriller",
          "science fiction action"
        ],
        "countries": [
          "United States",
          "United Kingdom"
        ],
        "languages": [
          "French",
          "English",
          "Japanese"
        ],
        "directors": [
          "Christopher Nolan"
        ],
        "cast": [
          "Leonardo DiCaprio",
          "Michael Caine",
          "Marion Cotillard",
          "Cillian Murphy",
          "Tom Hardy"
        ],
        "castTotal": 21,
        "writers": [
          "Christopher Nolan"
        ],
        "producers": [
          "Christopher Nolan",
          "Emma Thomas"
        ],
        "composers": [
          "Hans Zimmer"
        ],
        "cinematographers": [
          "Wally Pfister"
        ],
        "editors": [
          "Lee Smith"
        ],
        "productionCompanies": [
          "Warner Bros. Entertainment",
          "Legendary Pictures",
          "Syncopy Inc.",
          "Warner Bros. Pictures"
        ],
        "distributors": [
          "Netflix",
          "InterCom"
        ],
        "originalNetworks": [],
        "contentRating": "PG-13",
        "basedOn": null,
        "series": {
          "partOf": null,
          "follows": null,
          "followedBy": null
        },
        "awards": {
          "won": 7,
          "nominations": 8,
          "notable": [
            "Academy Award for Best Cinematography",
            "Academy Award for Best Visual Effects",
            "Academy Award for Best Sound Editing",
            "Academy Award for Best Sound",
            "Hugo Award for Best Dramatic Presentation, Long Form",
            "Saturn Award for Best Science Fiction Film",
            "National Board of Review: Top Ten Films"
          ]
        },
        "boxOfficeUsd": 836848102,
        "budgetUsd": 160000000,
        "filmingLocations": [
          "Japan",
          "Paris",
          "California",
          "Morocco",
          "Tokyo",
          "Alberta",
          "Tangier",
          "University College London",
          "pont de Bir-Hakeim",
          "Malibu",
          "Farnborough Airport",
          "Palais Galliera",
          "Commodore Schuyler F. Heim Bridge",
          "Fortress Mountain Resort",
          "RAF Cardington"
        ],
        "settings": [
          "Los Angeles",
          "Paris",
          "Australia"
        ],
        "scores": {
          "rating": 85,
          "confidence": "high",
          "acclaim": 99,
          "popularity": 99
        },
        "ids": {
          "imdb": "tt1375666",
          "tmdb": "27205",
          "wikidata": "Q25188"
        }
      }
    ],
    "dataAsOf": "2026-11-22"
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

FieldTypeExampleDescription
querystring"Inception"The title, IMDb id or Wikidata id looked up
countnumber1Number of movies returned
moviesarray[1]Matching movies, best-known first
titlestring"Inception"English title, or the original title when there is none
originalTitlestring"Inception"Title in the original language
yearnumber2010Year of first release
releaseDatestring"2010-07-08"Earliest known release date (YYYY-MM-DD); null when only the year is known
typestring"film"Kind of work: film for a feature, otherwise the specific kind, e.g. animated film, documentary film, short film, anime film, television film, television special, music video or video album
runtimeMinutesnumber148Running time in minutes
descriptionstring"2010 film directed by Christopher Nolan"One-line description
genresarray[drama, ...]Genres, e.g. science fiction, heist, drama
countriesarray[United States, ...]Countries of origin
languagesarray[French, ...]Original languages
directorsarray[Christopher Nolan]Directors
castarray[Leonardo DiCaprio, ...]Cast, best-known first: the top 5, or everyone with cast=true
castTotalnumber21Number of cast members on record
writersPremiumarray[Christopher Nolan]Screenwriters
producersPremiumarray[Christopher Nolan, ...]Producers
composersPremiumarray[Hans Zimmer]Composers of the score
cinematographersPremiumarray[Wally Pfister]Directors of photography
editorsPremiumarray[Lee Smith]Film editors
productionCompaniesPremiumarray[Warner Bros. Entertainment, ...]Production companies
distributorsPremiumarray[Netflix, ...]Distributors
originalNetworksPremiumarray[]Networks or streaming services the film premiered on, e.g. HBO or Netflix; mostly set for TV films and specials, empty for theatrical releases
contentRatingstring"PG-13"US MPA rating, e.g. PG-13; null when not on record
basedOnPremiumobjectnullThe work the film is based on, e.g. a novel or play
seriesobject{...}Franchise links
partOfPremiumobjectnullFilm series or franchise
followsPremiumobjectnullThe previous film: title and Wikidata id
followedByPremiumobjectnullThe next film: title and Wikidata id
awardsobject{...}Awards record
wonPremiumnumber7Number of awards won
nominationsPremiumnumber8Number of award nominations
notablePremiumarray[Academy Award for Best Cinematography, ...]Up to 10 awards won, most prestigious first
boxOfficeUsdPremiumnumber836848102Box office gross in US dollars, the largest figure on record
budgetUsdPremiumnumber160000000Production budget in US dollars
filmingLocationsPremiumarray[Japan, ...]Places the film was shot
settingsPremiumarray[Los Angeles, ...]Places the story is set
scoresobject{...}APIVerve movie scores
ratingPremiumnumber85APIVerve's 0-100 movie rating, from the film's recorded critical and audience reception adjusted for acclaim and popularity; null when no reception is on record
confidencePremiumstring"high"How much reception data the rating rests on: high, medium or low; null with no rating
acclaimPremiumnumber99Awards prestige, 0-100 against every film in the catalog
popularityPremiumnumber99How widely known the film is, 0-100 against every film in the catalog, from its worldwide encyclopedia coverage and monthly English Wikipedia readership
idsobject{...}Identifiers in other databases
imdbstring"tt1375666"IMDb title id, e.g. tt1375666
tmdbstring"27205"The Movie Database id
wikidatastring"Q25188"Wikidata id; pass it back as id for an exact lookup
dataAsOfstring"2026-11-22"Date the movie data was last refreshed (YYYY-MM-DD)

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change. Error handling covers the full status list and which of them are worth retrying.

StatusMeaningWhat to do
400Input was rejectedRead error; it names the parameter.
401Key missing or invalidCheck the header name and the key value.
403Key valid, but not permittedA key restriction or IP allow-list; see key scoping.
429Rate limited, or out of creditsRead error to tell them apart; see rate limits.

Use cases

Watchlist and Tracking Apps
Turn a typed title into a full film card with year, runtime, genres, cast and a rating, and store the IMDb and TMDB ids to link out.
Recommendation Engines
Feed genres, directors, cast, acclaim and popularity into similarity models, and use the rating to rank what to suggest next.
Trivia and Quiz Games
Generate questions from release years, directors, box office, awards and filming locations across 450,000 films.
Media Catalogs and Libraries
Enrich a video library or film archive with credits, studios, content ratings and franchise order from a title or IMDb id.

Other ways to use Movie Lookup

Set up Movie Lookup on APIVerve, or reach the same source a different way. Your APIVerve account and credits work on all of them — one key, one balance.

Give it to an AI agentConnect over MCP and your agent calls it as a native tool — Claude, Cursor, ChatGPT.VerveKit →Reference →
Google Sheets or ExcelA =VERVE() formula fills a column — no script, no export, recalculates in place.VerveSheets →Reference →
Ground an agent on itA cited, machine-checkable fact your model can't produce on its own.VerveContext →Reference →

More in Entertainment:

Was this page helpful?