Chart - hooshid/imdb-scraper GitHub Wiki

Chart Class

The Chart class provides access to various IMDb charts including box office data, top rated lists, and popularity rankings.

getBoxOffice()

Method Documentation

Retrieves the current weekend box office results for US theaters, including earnings data and film metadata.

Method Signature

public function getBoxOffice(): array

Example Usage

$chart = new \Hooshid\ImdbScraper\Chart();
$boxOffice = $chart->getBoxOffice();

Return Value

Key Type Description
weekend_start_date string|null Start date of weekend period (YYYY-MM-DD)
weekend_end_date string|null End date of weekend period (YYYY-MM-DD)
list array[] Array of box office entries
list[].id string IMDb title ID
list[].title string Film title
list[].rating float|null Average user rating
list[].votes int|null Number of user ratings
list[].lifetime_gross_amount int|null Total domestic gross earnings
list[].lifetime_gross_currency string|null Currency code for earnings
list[].weekend_gross_amount int|null Weekend gross earnings
list[].weekend_gross_currency string|null Currency code for earnings
list[].weeks_released int|null Number of weeks in release
list[].image array|null Primary image data
list[].image.url string Image URL
list[].image.width int Image width in pixels
list[].image.height int Image height in pixels

Example Return

{
    "weekend_start_date": "2025-06-20",
    "weekend_end_date": "2025-06-22",
    "list": [
        {
            "id": "tt26743210",
            "title": "How to Train Your Dragon",
            "rating": 8.1,
            "votes": 36312,
            "lifetime_gross_amount": 171805710,
            "lifetime_gross_currency": "USD",
            "weekend_gross_amount": 36577190,
            "weekend_gross_currency": "USD",
            "weeks_released": 2,
            "image": {
                "url": "https://m.media-amazon.com/images/M/MV5BODA5Y2M0NjctNWQzMy00ODRhLWE0MzUtYmE1YTAzZjYyYmQyXkEyXkFqcGc@._V1_.jpg",
                "width": 3158,
                "height": 5000
            }
        }
    ]
}

Error Handling

  • Returns empty array if no box office data available
  • Throws Exception on API request failure

Notes

  • Only returns top 10 box office performers
  • Earnings data is for domestic (US) market only
  • Week counts start from first wide release date

getList()

Method Documentation

Retrieves ranked lists of titles such as the IMDb Top 250 or genre-specific rankings.

Method Signature

public function getList(string $listType): array

Parameters

Parameter Type Default Required Description
listType string YES Type of list to retrieve

Valid listType Values

  • TOP_250: Top 250 Movies
  • TOP_250_TV: Top 250 TV Shows
  • TOP_250_ENGLISH: Top 250 English Movies
  • TOP_250_INDIA: Top 250 Indian Movies
  • TOP_50_TELUGU: Top 50 Telugu Movies
  • TOP_50_TAMIL: Top 50 Tamil Movies
  • TOP_50_MALAYALAM: Top 50 Malayalam Movies
  • TOP_50_BENGALI: Top 50 Bengali Movies
  • BOTTOM_100: Bottom 100 Movies

Example Usage

$chart = new \Hooshid\ImdbScraper\Chart();
$topMovies = $chart->getList('TOP_250');
$bottomMovies = $chart->getList('BOTTOM_100');

Return Value

Key Type Description
id string IMDb title ID
title string Title name
rank int Current ranking position
type string|null Title type (Movie/TV/etc)
runtime_minutes int|null Runtime in minutes
runtime_seconds int|null Runtime in seconds
year int|null Release year
rating float|null Average rating
votes int|null Number of votes
image array|null Primary image data
image.url string Image URL
image.width int Image width
image.height int Image height

Example Return

[
    {
        "id": "tt0111161",
        "title": "The Shawshank Redemption",
        "rank": 1,
        "type": "Movie",
        "runtime_minutes": 142,
        "runtime_seconds": 8520,
        "year": 1994,
        "rating": 9.3,
        "votes": 3060742,
        "image": {
            "url": "https://m.media-amazon.com/images/M/MV5BMDAyY2FhYjctNDc5OS00MDNlLThiMGUtY2UxYWVkNGY2ZjljXkEyXkFqcGc@._V1_.jpg",
            "width": 1200,
            "height": 1800
        }
    }
]

Error Handling

  • Returns empty array for invalid listType
  • Throws Exception on API request failure

Notes

  • Lists are updated daily
  • Some lists may contain fewer than the maximum items

getMostPopularTitles()

Method Documentation

Retrieves popularity-based charts that can be filtered by genre.

Method Signature

public function getMostPopularTitles(string $listType, string $genreId = null): array

Parameters

Parameter Type Default Required Description
listType string YES Type of chart to retrieve
genreId string|null null NO Optional genre filter

Valid listType Values

  • MOST_POPULAR_MOVIES
  • TOP_RATED_MOVIES
  • LOWEST_RATED_MOVIES
  • TOP_RATED_ENGLISH_MOVIES
  • MOST_POPULAR_TV_SHOWS
  • TOP_RATED_TV_SHOWS

Example Usage

$chart = new \Hooshid\ImdbScraper\Chart();
$popular = $chart->getMostPopularTitles('MOST_POPULAR_MOVIES');
$horror = $chart->getMostPopularTitles('TOP_RATED_MOVIES', 'Horror');

Return Value

Key Type Description
id string IMDb title ID
title string Title name
rank int Current popularity rank
type string|null Title type
runtime_minutes int|null Runtime in minutes
runtime_seconds int|null Runtime in seconds
genres string[] Array of genre names
year int|null Release year
rating float|null Average rating
votes int|null Number of votes
image array|null Primary image data
image.url string Image URL
image.width int Image width
image.height int Image height

Example Return

[
    {
        "id": "tt10548174",
        "title": "28 Years Later",
        "rank": 1,
        "type": "Movie",
        "runtime_minutes": 115,
        "runtime_seconds": 6900,
        "genres": ["Horror","Thriller"],
        "year": 2025,
        "rating": 7.2,
        "votes": 33189,
        "image": {
            "url": "https://m.media-amazon.com/images/M/MV5BNjgwYTI0YjctMWYzNS00MmI1LWI5YTctNmE1YjBkNDFlNWMxXkEyXkFqcGc@._V1_.jpg",
            "width": 1080,
            "height": 1350
        }
    }
]

Error Handling

  • Returns empty array for invalid listType
  • Throws Exception on API request failure

Notes

  • Genre filter only applies to movie lists
  • Popularity ranks update frequently

getMostPopularNames()

Method Documentation

Retrieves the top 100 most popular celebrities from IMDb's Starmeter chart.

Method Signature

public function getMostPopularNames(): array

Example Usage

$chart = new \Hooshid\ImdbScraper\Chart();
$stars = $chart->getMostPopularNames();

Return Value

Key Type Description
id string IMDb name ID
name string Full name
rank int|null Current starmeter rank
professions string[] Array of profession categories
known_for array[] Notable works
known_for[].id string Title ID
known_for[].title string Title name
known_for[].year int|null Release year
known_for[].end_year int|null End year (for series)
image array|null Primary image data
image.url string Image URL
image.width int Image width
image.height int Image height

Example Return

[
    {
        "id": "nm0328828",
        "name": "Matthew Goode",
        "rank": 1,
        "professions": ["Actor","Self","Archive Footage"],
        "known_for": [
            {
                "id": "tt2084970",
                "title": "The Imitation Game",
                "year": 2014,
                "end_year": null
            }
        ],
        "image": {
            "url": "https://m.media-amazon.com/images/M/MV5BMTY5MDI4NzkxOV5BMl5BanBnXkFtZTgwNzc2MzU0MzE@._V1_.jpg",
            "width": 1360,
            "height": 2048
        }
    }
]

Error Handling

  • Returns empty array if no data available
  • Throws Exception on API request failure

Notes

  • Starmeter ranks update frequently based on page views
  • Known-for titles are limited to 5 per person
  • Profession categories indicate primary roles