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