Skip to content

TitleSearch

Jump to bottom
Alireza Kamali edited this page Oct 18, 2024 · 1 revision

TitleSearch Class

The TitleSearch class extends the Base class and provides functionality to search for movie and TV show titles using various parameters. The default parameters are all empty as you need to provide search input. Calling search method without any parameters returns empty array, no point to search, so at least one parameter has to be provided!

search(array $params = []) : array

This method performs an advanced title search based on the parameters provided. It returns an array of search results.

Parameters

Parameter Type Description Example
searchTerm string Search term for title text. "Inception"
types string A comma-separated list of title type IDs. "movie,tvSeries"
genres string A comma-separated list of genre IDs. "Action,Drama"
creditId string IMDb name ID for searching based on credited names (works only with nameID). "nm0001228" (Peter Fonda)
startDate string Search for titles released from this date onward (ISO format). "1975-01-01"
endDate string Search for titles released until this date (ISO format). If both dates are provided, searches within the date span. "2020-12-31"
countries string A comma-separated list of ISO 3166 country codes. "US,DE"
languages string A comma-separated list of ISO 639 language codes. "en,de"
adult string Filter explicit content. Accepts INCLUDE_ADULT or EXCLUDE_ADULT. Default is EXCLUDE_ADULT. "EXCLUDE_ADULT"
limit int Limit the number of results. Default is 50. 100
sortBy string Sort results by one of the available sorting options (see below). Default is POPULARITY. "BOX_OFFICE_GROSS_DOMESTIC"
sortOrder string Sort order. Accepts ASC (ascending) or DESC (descending). Default is ASC. "DESC"

Title Type IDs

The following title type IDs can be used in the types parameter:

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

Genre IDs

The following genre IDs can be used in the genres parameter:

  • 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

Sorting Options

You can sort the results using the sortBy parameter with one of the following options:

Sort By Description
BOX_OFFICE_GROSS_DOMESTIC Gross revenue pulled in via box-office in the Domestic market (U.S., Canada, and Puerto Rico).
METACRITIC_SCORE Overall Metascore based on critic reviews. Titles without a metascore are placed at the end when using ASC.
MY_RATING Star Rating given by the requesting user.
MY_RATING_DATE Date when the user rated a title.
POPULARITY Title popularity based on IMDb's TitleMeter (non-episodic titles).
RANKING Ranking based on a specific ranking algorithm (requires a ranked title list constraint).
RELEASE_DATE Earliest wide release date of a title. Titles without a release date are placed at the end when using ASC.
RUNTIME The length of the title in terms of runtime. Shorter titles will appear first when sorting by ASC.
TITLE_REGIONAL Alphabetical sorting based on regional title text determined by user language preferences. Defaults to original title otherwise.
USER_RATING Weighted IMDb Star Rating as determined by users. Titles with fewer ratings are placed at the end when using ASC.
USER_RATING_COUNT Count of ratings given by users. Titles with fewer ratings are placed at the end when using ASC.
YEAR The recognized year of the title. Older titles will appear first when sorting by ASC.

Example Usage

$titleSearch = new TitleSearch();
$params = [
    'searchTerm' => 'Inception',
    'genres' => 'Action,Drama',
    'types' => 'movie',
    'startDate' => '2000-01-01',
    'endDate' => '2020-12-31',
    'countries' => 'US,DE',
    'languages' => 'en,de',
    'adult' => 'EXCLUDE_ADULT',
    'limit' => 10,
    'sortBy' => 'RELEASE_DATE',
    'sortOrder' => 'DESC'
];

$results = $titleSearch->search($params);

This will search for movies with the title "Inception" that fall under the genres "Action" and "Drama," released between 2000 and 2020, and sort the results by release date in descending order.

Return Example

The search() method returns an array of titles with the following structure:

[
    [
        'id' => 'tt1375666',
        'url' => 'https://www.imdb.com/title/tt1375666',
        'originalTitle' => 'Inception',
        'title' => 'Inception',
        'type' => 'movie',
        'year' => '2010',
        'imageUrl' => ['original' => 'https://some-image-url.com/inception.jpg']
    ]
    // ... more results
]

External References

Clone this wiki locally