Here's the comprehensive documentation for the NameSearch class:

NameSearch Class

Class Overview

The NameSearch class provides advanced search functionality for names (actors, directors, etc.) on IMDb. It allows filtering by various criteria including name, birth/death dates, gender, and more. The search results include detailed information about each person including their image, professions, biography, and known works.

search Method

Method Description

Performs an advanced name search on IMDb with multiple filtering options. Returns an array of matching names with detailed information including professions, biography, known works, and images.

Method Signature

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

Parameters

Parameter	Type	Default	Required	Description
name	string	""	NO	Full or partial name to search
birthMonthDay	string	""	NO	Month and day in MM-DD format (e.g. "04-02")
birthDateRangeStart	string	""	NO	Birth date range start (YYYY-MM-DD)
birthDateRangeEnd	string	""	NO	Birth date range end (YYYY-MM-DD)
deathDateRangeStart	string	""	NO	Death date range start (YYYY-MM-DD)
deathDateRangeEnd	string	""	NO	Death date range end (YYYY-MM-DD)
birthPlace	string	""	NO	Birth place location
gender	string	""	NO	Gender filter
adult	string	"EXCLUDE_ADULT"	NO	Adult content filter
limit	int	50	NO	Maximum results
sortBy	string	"POPULARITY"	NO	Sort field
sortOrder	string	"ASC"	NO	Sort direction

gender Parameter Values

• MALE
• FEMALE
• NON_BINARY
• OTHER

adult Parameter Values

• INCLUDE_ADULT
• EXCLUDE_ADULT

sortBy Parameter Values

• POPULARITY
• NAME
• BIRTH_DATE
• DEATH_DATE

sortOrder Parameter Values

• ASC
• DESC

Example Usage

$nameSearch = new NameSearch();
$results = $nameSearch->search([
    'name' => 'Emma',
    'birthMonthDay' => '04-02',
    'gender' => 'FEMALE',
    'limit' => 10,
    'sortBy' => 'POPULARITY'
]);

Return Value

Key	Type	Description
results	array	Array of matched names
total	int	Total number of matching results

results Array Structure

Key	Type	Description
index	int	Result position
id	string	IMDb name ID
url	string	Full IMDb URL
name	string	Full name
image	array|null	Primary image with dimensions
professions	string[]	Array of primary professions
bio	string|null	Biography text
known_for	array	Notable works with title IDs and years

image Array Structure

Key	Type	Description
url	string	Image URL
width	int	Image width in pixels
height	int	Image height in pixels

known_for Array Structure

Key	Type	Description
id	string	IMDb title ID
title	string	Title name
year	int|null	Release year
end_year	int|null	End year for series

Example Return

[
    'results' => [
        [
            'index' => 1,
            'id' => 'nm3528821',
            'url' => 'https://www.imdb.com/name/nm3528821/',
            'name' => 'Emma Myers',
            'image' => [
                'url' => 'https://m.media-amazon.com/images/M/...jpg',
                'width' => 2667,
                'height' => 4000
            ],
            'professions' => ['Actress'],
            'bio' => 'Emma Myers was born on 2 April 2002...',
            'known_for' => [
                [
                    'id' => 'tt13443470',
                    'title' => 'Wednesday',
                    'year' => 2022,
                    'end_year' => null
                ]
            ]
        ]
    ],
    'total' => 18236
]

Error Handling

• Returns empty results array if:
  • No search constraints provided
  • No matching results found
  • Invalid API response structure
• Throws Exception if:
  • API request fails
  • Invalid date formats provided

Notes

• At least one search parameter should be provided for meaningful results
• Date parameters must be in valid YYYY-MM-DD format
• The limit parameter controls how many results are returned. Adjust this value for performance when large datasets are queried.
• The 'total' count may be higher than the number of returned results due to pagination (limit parameter)
• Biography text may contain HTML line breaks
• known_for entries are limited to 5 per result by default