0
# Movie Operations
1

2
Comprehensive movie search, retrieval, and information management including search functionality, detailed information retrieval, and specialized movie lists and charts.
3

4
## Capabilities
5

6
### Movie Search
7

8
Search for movies by title with configurable result limits and search options.
9

10
```python { .api }
11
def search_movie(title, results=None):
12
    """
13
    Search for movies by title.
14
    
15
    Parameters:
16
    - title: str - Movie title to search for
17
    - results: int, optional - Maximum number of results (default: instance default)
18
    
19
    Returns:
20
    list: List of Movie objects with basic information
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
from imdb import IMDb
28

29
ia = IMDb()
30

31
# Basic movie search
32
movies = ia.search_movie('The Matrix')
33
print(f"Found {len(movies)} movies")
34
for movie in movies[:3]:
35
    print(f"- {movie['title']} ({movie.get('year', 'N/A')})")
36

37
# Limited results
38
movies = ia.search_movie('Matrix', results=5)
39
```
40

41
### Advanced Movie Search
42

43
Advanced movie search with multiple criteria and sorting options.
44

45
```python { .api }
46
def search_movie_advanced(title=None, adult=None, results=None, sort=None, sort_dir=None):
47
    """
48
    Advanced search for movies with multiple criteria.
49
    
50
    Parameters:
51
    - title: str, optional - Movie title
52
    - adult: bool, optional - Include adult content
53
    - results: int, optional - Maximum number of results
54
    - sort: str, optional - Sort criteria
55
    - sort_dir: str, optional - Sort direction ('asc', 'desc')
56
    
57
    Returns:
58
    list: List of Movie objects matching criteria
59
    """
60
```
61

62
### Episode Search
63

64
Search specifically for TV series episodes.
65

66
```python { .api }
67
def search_episode(title, results=None):
68
    """
69
    Search for TV series episodes by title.
70
    
71
    Parameters:
72
    - title: str - Episode title to search for
73
    - results: int, optional - Maximum number of results
74
    
75
    Returns:
76
    list: List of Movie objects representing episodes
77
    """
78
```
79

80
### Movie Retrieval
81

82
Retrieve detailed movie information by IMDb ID with configurable information sets.
83

84
```python { .api }
85
def get_movie(movieID, info=('main', 'plot'), modFunct=None):
86
    """
87
    Get movie by ID with specified information sets.
88
    
89
    Parameters:
90
    - movieID: str - Movie ID (internal or IMDb format)
91
    - info: tuple/list - Information sets to retrieve ('main', 'plot', 'full_credits', etc.)
92
    - modFunct: function, optional - String modification function
93
    
94
    Returns:
95
    Movie: Movie object with requested information
96
    
97
    See also: Data Container Classes for Movie object details
98
    """
99
```
100

101
**Available Information Sets:**
102
- `'main'` - Basic movie information (title, year, rating, etc.)
103
- `'plot'` - Plot summaries and synopses
104
- `'full_credits'` - Complete cast and crew information
105
- `'awards'` - Awards and nominations
106
- `'taglines'` - Movie taglines
107
- `'keywords'` - Associated keywords
108
- `'quotes'` - Memorable quotes
109
- `'trivia'` - Trivia and facts
110
- `'goofs'` - Mistakes and goofs
111
- `'connections'` - Related movies
112
- `'technical'` - Technical specifications
113
- `'locations'` - Filming locations
114
- `'soundtrack'` - Soundtrack information
115
- `'reviews'` - User reviews
116
- `'episodes'` - TV series episodes
117
- `'faqs'` - Frequently asked questions
118

119
**Usage Example:**
120

121
```python
122
from imdb import IMDb
123

124
ia = IMDb()
125

126
# Get movie with basic info
127
movie = ia.get_movie('0133093')  # The Matrix
128
print(f"Title: {movie['title']}")
129
print(f"Year: {movie['year']}")
130

131
# Get movie with multiple info sets
132
movie = ia.get_movie('0133093', info=['main', 'plot', 'full_credits'])
133
print(f"Plot: {movie['plot'][0]}")
134
print(f"Director: {movie['director'][0]['name']}")
135
print(f"Cast: {[actor['name'] for actor in movie['cast'][:5]]}")
136
```
137

138
### Episode Retrieval
139

140
Alias for get_movie specifically for TV episodes.
141

142
```python { .api }
143
get_episode = get_movie
144
```
145

146
### Top Movie Charts
147

148
Retrieve various IMDb top movie lists and charts.
149

150
```python { .api }
151
def get_top250_movies():
152
    """
153
    Get IMDb Top 250 movies list.
154
    
155
    Returns:
156
    list: List of Movie objects representing top 250 movies
157
    """
158

159
def get_bottom100_movies():
160
    """
161
    Get IMDb Bottom 100 movies list.
162
    
163
    Returns:
164
    list: List of Movie objects representing bottom 100 movies
165
    """
166

167
def get_top250_tv():
168
    """
169
    Get IMDb Top 250 TV shows list.
170
    
171
    Returns:
172
    list: List of Movie objects representing top 250 TV shows
173
    """
174

175
def get_popular100_movies():
176
    """
177
    Get 100 most popular movies.
178
    
179
    Returns:
180
    list: List of Movie objects representing most popular movies
181
    """
182

183
def get_popular100_tv():
184
    """
185
    Get 100 most popular TV shows.
186
    
187
    Returns:
188
    list: List of Movie objects representing most popular TV shows
189
    """
190

191
def get_top250_indian_movies():
192
    """
193
    Get top 250 Indian movies.
194
    
195
    Returns:
196
    list: List of Movie objects representing top Indian movies
197
    """
198

199
def get_boxoffice_movies():
200
    """
201
    Get current box office movies.
202
    
203
    Returns:
204
    list: List of Movie objects representing current box office hits
205
    """
206
```
207

208
**Usage Example:**
209

210
```python
211
from imdb import IMDb
212

213
ia = IMDb()
214

215
# Get top movies
216
top_movies = ia.get_top250_movies()
217
print(f"#1 Movie: {top_movies[0]['title']} ({top_movies[0]['year']})")
218

219
# Get popular movies
220
popular = ia.get_popular100_movies()
221
print(f"Currently popular: {popular[0]['title']}")
222
```
223

224
### Genre-Based Top Lists
225

226
Retrieve top movies and TV shows filtered by genre.
227

228
```python { .api }
229
def get_top50_movies_by_genres(genres):
230
    """
231
    Get top 50 movies by genre(s).
232
    
233
    Parameters:
234
    - genres: str or list - Genre name or list of genre names
235
    
236
    Returns:
237
    list: List of Movie objects representing top movies in specified genres
238
    """
239

240
def get_top50_tv_by_genres(genres):
241
    """
242
    Get top 50 TV shows by genre(s).
243
    
244
    Parameters:
245
    - genres: str or list - Genre name or list of genre names
246
    
247
    Returns:
248
    list: List of Movie objects representing top TV shows in specified genres
249
    """
250
```
251

252
**Usage Example:**
253

254
```python
255
from imdb import IMDb
256

257
ia = IMDb()
258

259
# Single genre
260
action_movies = ia.get_top50_movies_by_genres('Action')
261

262
# Multiple genres
263
comedy_drama = ia.get_top50_movies_by_genres(['Comedy', 'Drama'])
264

265
# TV shows by genre
266
sci_fi_tv = ia.get_top50_tv_by_genres('Sci-Fi')
267
```
268

269
### Movie Lists
270

271
Retrieve movies from specific IMDb lists by list ID.
272

273
```python { .api }
274
def get_movie_list(list_id, results=None):
275
    """
276
    Get movies from IMDb list by ID.
277
    
278
    Parameters:
279
    - list_id: str - IMDb list ID
280
    - results: int, optional - Maximum number of results
281
    
282
    Returns:
283
    list: List of Movie objects from the specified list
284
    """
285
```
286

287
### Movie Information Sets
288

289
Get available information sets for movie objects.
290

291
```python { .api }
292
def get_movie_infoset():
293
    """
294
    Get list of available information sets for movies.
295
    
296
    Returns:
297
    list: Available information set names
298
    """
299
```
300

301
### Series Season Updates
302

303
Update TV series with specific season information.
304

305
```python { .api }
306
def update_series_seasons(movie, season_nums, override=0):
307
    """
308
    Update TV series movie object with specific seasons.
309
    
310
    Parameters:
311
    - movie: Movie - TV series Movie object
312
    - season_nums: list - List of season numbers to retrieve
313
    - override: int - Whether to override existing information (0/1)
314
    """
315
```
316

317
**Usage Example:**
318

319
```python
320
from imdb import IMDb
321

322
ia = IMDb()
323

324
# Get TV series
325
series = ia.get_movie('0903747')  # Breaking Bad
326

327
# Update with specific seasons
328
ia.update_series_seasons(series, [1, 2, 3])
329

330
# Access season information
331
if 'episodes' in series:
332
    for season_num, episodes in series['episodes'].items():
333
        print(f"Season {season_num}: {len(episodes)} episodes")
334
```
335

336
## Movie Object Integration
337

338
All movie search and retrieval functions return Movie objects that can be further updated with additional information:
339

340
```python
341
from imdb import IMDb
342

343
ia = IMDb()
344

345
# Search and get basic movie
346
movies = ia.search_movie('Inception')
347
movie = movies[0]
348

349
# Update with additional information
350
ia.update(movie, info=['plot', 'full_credits', 'awards'])
351

352
# Access detailed information
353
print(f"Plot: {movie.get('plot', ['N/A'])[0]}")
354
print(f"Awards: {len(movie.get('awards', []))} awards")
355
```
356

357
See also: [Data Container Classes](./data-containers.md) for complete Movie object documentation.
358

359
## Error Handling Best Practices
360

361
Common error scenarios and robust handling patterns for movie operations:
362

363
```python
364
from imdb import IMDb, IMDbError, IMDbDataAccessError
365

366
ia = IMDb()
367

368
# Robust movie search with error handling
369
def safe_movie_search(title, max_results=5):
370
    try:
371
        movies = ia.search_movie(title, results=max_results)
372
        if not movies:
373
            print(f"No movies found for '{title}'")
374
            return []
375
        return movies
376
    except IMDbDataAccessError as e:
377
        print(f"Network/data access error: {e}")
378
        return []
379
    except IMDbError as e:
380
        print(f"IMDb error: {e}")
381
        return []
382

383
# Robust movie information retrieval
384
def safe_get_movie_info(movie_id, info_sets=['main', 'plot']):
385
    try:
386
        movie = ia.get_movie(movie_id, info=info_sets)
387
        return movie
388
    except IMDbDataAccessError as e:
389
        print(f"Cannot access movie {movie_id}: {e}")
390
        return None
391
    except IMDbError as e:
392
        print(f"Error retrieving movie {movie_id}: {e}")
393
        return None
394

395
# Safe chart operations with fallback
396
def get_top_movies_safe():
397
    try:
398
        return ia.get_top250_movies()
399
    except IMDbError as e:
400
        print(f"Cannot retrieve top movies: {e}")
401
        # Fallback to search for popular movies
402
        return ia.search_movie("popular", results=10)
403
```