TitleSearch - hooshid/imdb-scraper GitHub Wiki

TitleSearch Class

Method Documentation

The TitleSearch class provides advanced search functionality for IMDb titles with extensive filtering capabilities. It allows searching by title text, type, genre, release date, country, language, and other criteria, returning structured results with detailed title information.

search()

Method Signature

public function search(array $params = []): array

Parameters

Parameter Type Default Required Description
searchTerm string "" NO Title to search for
types string "" NO Comma-separated title types
genres string "" NO Comma-separated genres
creditId string "" NO Comma-separated name IDs to filter by
startDate string "" NO Start of release date range (YYYY-MM-DD)
endDate string "" NO End of release date range (YYYY-MM-DD)
countries string "" NO Comma-separated country codes
languages string "" NO Comma-separated language codes
companies string "" NO Comma-separated company IDs
keywords string "" NO Comma-separated keywords
adult string "EXCLUDE_ADULT" NO Content filter
limit int 50 NO Results per page
sortBy string "POPULARITY" NO Field to sort by
sortOrder string "ASC" NO Sort direction

types Parameter Values

  • movie
  • tvSeries
  • short
  • tvEpisode
  • tvMiniSeries
  • tvMovie
  • tvSpecial
  • tvShort
  • videoGame
  • video
  • musicVideo
  • podcastSeries
  • podcastEpisode

genres Parameter Values

  • Action
  • Adult
  • Adventure
  • Animation
  • Biography
  • Comedy
  • Crime
  • Documentary
  • Drama
  • Family
  • Fantasy
  • Film-Noir
  • Game-Show
  • History
  • Horror
  • Music
  • Musical
  • Mystery
  • News
  • Reality-TV
  • Romance
  • Sci-Fi
  • Short
  • Sport
  • Talk-Show
  • Thriller
  • War
  • Western

adult Parameter Values

  • EXCLUDE_ADULT
  • INCLUDE_ADULT

sortBy Parameter Values

  • POPULARITY
  • RANKING
  • RELEASE_DATE
  • YEAR
  • RUNTIME
  • BOX_OFFICE_GROSS_DOMESTIC
  • METACRITIC_SCORE

sortOrder Parameter Values

  • ASC
  • DESC

Example Usage

$titleSearch = new TitleSearch();
$results = $titleSearch->search([
    'searchTerm' => 'Harry Potter',
    'types' => 'movie,tvSeries',
    'genres' => 'Adventure,Fantasy',
    'limit' => 10,
    'sortBy' => 'RELEASE_DATE',
    'sortOrder' => 'DESC'
]);

Return Value

Key Type Description
results array[] Array of matched titles
total int Total number of matching results
results[].id string IMDb title ID
results[].url string Full IMDb URL for the title
results[].title string Display title
results[].original_title string|null Original title if different
results[].type string|null Title type (Movie, TV Series, etc)
results[].year int|null Release year
results[].end_year int|null End year for series
results[].plot string|null Plot summary
results[].runtime_formatted string|null Runtime in HH:MM:SS format
results[].runtime_minutes int|null Runtime in minutes
results[].runtime_seconds int|null Runtime in seconds
results[].rating float|null Average user rating
results[].votes int|null Number of votes
results[].metacritic int|null Metacritic score
results[].image array|null Primary image data
results[].image.url string Image URL
results[].image.width int Image width in pixels
results[].image.height int Image height in pixels

Example Return

[
    "results" => [
        [
            "id" => "tt0241527",
            "url" => "https://www.imdb.com/title/tt0241527/",
            "title" => "Harry Potter and the Sorcerer's Stone",
            "original_title" => "Harry Potter and the Sorcerer's Stone",
            "type" => "Movie",
            "year" => 2001,
            "end_year" => null,
            "plot" => "An orphaned boy enrolls in a school of wizardry...",
            "runtime_formatted" => "2:32:00",
            "runtime_minutes" => 152,
            "runtime_seconds" => 9120,
            "rating" => 7.7,
            "votes" => 908830,
            "metacritic" => 65,
            "image" => [
                "url" => "https://m.media-amazon.com/images/M/...jpg",
                "width" => 1972,
                "height" => 2902
            ]
        ]
    ],
    "total" => 4269
]

Error Handling

  • Returns empty results array if:
    • No search parameters provided
    • Invalid date format in startDate/endDate
    • API request fails
  • Throws Exception for:
    • Network/connection issues
    • Invalid API responses

Notes

  • For best results, provide at least a searchTerm or one filter parameter
  • Date ranges must be in YYYY-MM-DD format
  • Multiple values in comma-separated fields (types, genres, etc) are treated as OR conditions
  • The total count may exceed the number of returned results due to pagination (limit parameter)
  • Some fields may be null for titles with incomplete data on IMDb

External References