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