0
# Advanced Features
1

2
Advanced functionality including URL/ID conversion, specialized charts, keyword operations, data updates, and utility methods for complex IMDb data operations.
3

4
## ID and URL Conversion
5

6
### IMDb ID Retrieval
7

8
Get IMDb IDs for objects or convert between different ID formats.
9

10
```python { .api }
11
def get_imdbID(mop):
12
    """
13
    Get IMDb ID for Movie/Person/Character/Company object.
14
    
15
    Parameters:
16
    - mop: Movie/Person/Character/Company - Object to get IMDb ID for
17
    
18
    Returns:
19
    str: IMDb ID (e.g., '0133093' for movies, '0000158' for people)
20
    """
21

22
def get_imdbMovieID(movieID):
23
    """
24
    Convert internal movieID to IMDb ID.
25
    
26
    Parameters:
27
    - movieID: str - Internal movie ID
28
    
29
    Returns:
30
    str: IMDb movie ID
31
    """
32

33
def get_imdbPersonID(personID):
34
    """
35
    Convert internal personID to IMDb ID.
36
    
37
    Parameters:
38
    - personID: str - Internal person ID
39
    
40
    Returns:
41
    str: IMDb person ID
42
    """
43

44
def get_imdbCharacterID(characterID):
45
    """
46
    Convert internal characterID to IMDb ID.
47
    
48
    Parameters:
49
    - characterID: str - Internal character ID
50
    
51
    Returns:
52
    str: IMDb character ID
53
    """
54

55
def get_imdbCompanyID(companyID):
56
    """
57
    Convert internal companyID to IMDb ID.
58
    
59
    Parameters:
60
    - companyID: str - Internal company ID
61
    
62
    Returns:
63
    str: IMDb company ID
64
    """
65
```
66

67
### Name/Title to IMDb ID Conversion
68

69
Convert text strings to IMDb IDs through search and matching.
70

71
```python { .api }
72
def title2imdbID(title, kind=None):
73
    """
74
    Convert movie title to IMDb ID through search.
75
    
76
    Parameters:
77
    - title: str - Movie title in plain text format
78
    - kind: str, optional - Movie kind (movie, tv series, etc.)
79
    
80
    Returns:
81
    str or list: IMDb ID or list of IDs if multiple matches
82
    """
83

84
def name2imdbID(name):
85
    """
86
    Convert person name to IMDb ID through search.
87
    
88
    Parameters:
89
    - name: str - Person name
90
    
91
    Returns:
92
    str: IMDb person ID or None if not found
93
    """
94

95
def character2imdbID(name):
96
    """
97
    Convert character name to IMDb ID through search.
98
    
99
    Parameters:
100
    - name: str - Character name
101
    
102
    Returns:
103
    str: IMDb character ID or None if not found
104
    """
105

106
def company2imdbID(name):
107
    """
108
    Convert company name to IMDb ID through search.
109
    
110
    Parameters:
111
    - name: str - Company name
112
    
113
    Returns:
114
    str: IMDb company ID or None if not found
115
    """
116
```
117

118
### URL Generation
119

120
Generate IMDb URLs for objects.
121

122
```python { .api }
123
def get_imdbURL(mop):
124
    """
125
    Get IMDb URL for Movie/Person/Character/Company object.
126
    
127
    Parameters:
128
    - mop: Movie/Person/Character/Company - Object to get URL for
129
    
130
    Returns:
131
    str: Full IMDb URL or None if unable to generate
132
    """
133
```
134

135
**Usage Example:**
136

137
```python
138
from imdb import IMDb
139

140
ia = IMDb()
141

142
# Get movie and its IMDb ID
143
movie = ia.get_movie('0133093')
144
imdb_id = ia.get_imdbID(movie)
145
print(f"IMDb ID: {imdb_id}")
146

147
# Get IMDb URL
148
url = ia.get_imdbURL(movie)
149
print(f"IMDb URL: {url}")
150

151
# Convert title to IMDb ID
152
movie_id = ia.title2imdbID('The Matrix', kind='movie')
153
print(f"Movie ID from title: {movie_id}")
154

155
# Convert person name to IMDb ID
156
person_id = ia.name2imdbID('Keanu Reeves')
157
print(f"Person ID from name: {person_id}")
158
```
159

160
## Keyword Operations
161

162
### Keyword Search
163

164
Search for existing keywords in the IMDb database.
165

166
```python { .api }
167
def search_keyword(keyword, results=None):
168
    """
169
    Search for existing keywords similar to the given one.
170
    
171
    Parameters:
172
    - keyword: str - Keyword to search for
173
    - results: int, optional - Maximum number of results (default: keywordsResults)
174
    
175
    Returns:
176
    list: List of keyword strings
177
    """
178
```
179

180
### Movies by Keyword
181

182
Retrieve movies associated with specific keywords.
183

184
```python { .api }
185
def get_keyword(keyword, results=None, page=None):
186
    """
187
    Get movies associated with a keyword.
188
    
189
    Parameters:
190
    - keyword: str - Keyword to search for
191
    - results: int, optional - Maximum number of results
192
    - page: int, optional - Page number for pagination
193
    
194
    Returns:
195
    list: List of Movie objects associated with the keyword
196
    """
197
```
198

199
**Usage Example:**
200

201
```python
202
from imdb import IMDb
203

204
ia = IMDb()
205

206
# Search for keywords
207
keywords = ia.search_keyword('space')
208
print(f"Found keywords: {keywords[:10]}")
209

210
# Get movies by keyword
211
space_movies = ia.get_keyword('space', results=20)
212
print(f"Found {len(space_movies)} movies with 'space' keyword")
213
for movie in space_movies[:5]:
214
    print(f"- {movie['title']} ({movie.get('year', 'N/A')})")
215
```
216

217
## Data Update Operations
218

219
### Object Updates
220

221
Update objects with additional information or refresh existing data.
222

223
```python { .api }
224
def update(mop, info=None, override=0):
225
    """
226
    Update Movie/Person/Character/Company object with additional information.
227
    
228
    Parameters:
229
    - mop: Movie/Person/Character/Company - Object to update
230
    - info: list/tuple/str - Information sets to retrieve ('all' for everything)
231
    - override: int - Whether to override existing info (0=no, 1=yes)
232
    """
233
```
234

235
**Usage Example:**
236

237
```python
238
from imdb import IMDb
239

240
ia = IMDb()
241

242
# Get movie with basic info
243
movie = ia.search_movie('Inception')[0]
244
print(f"Initial info: {movie.current_info}")
245

246
# Update with additional information
247
ia.update(movie, info=['plot', 'full_credits', 'awards'])
248
print(f"After update: {movie.current_info}")
249

250
# Update with all available information
251
ia.update(movie, info='all')
252
print(f"All info loaded: {movie.current_info}")
253

254
# Force refresh existing information
255
ia.update(movie, info=['main'], override=1)
256
```
257

258
## Showtimes and Theater Information
259

260
### Cinema Showtimes
261

262
Retrieve current cinema showtimes information.
263

264
```python { .api }
265
def get_showtimes():
266
    """
267
    Get cinema showtimes information.
268
    
269
    Returns:
270
    list: List of dictionaries with cinema and movie showtime information.
271
    Format: [{'cinema': 'Cinema Name', 'address and contacts': '...',
272
             'movies': [{'movie': MovieObject, 'showtimes': 'times'}]}]
273
    """
274
```
275

276
**Usage Example:**
277

278
```python
279
from imdb import IMDb
280

281
ia = IMDb()
282

283
# Get current showtimes
284
showtimes = ia.get_showtimes()
285
print(f"Found {len(showtimes)} cinemas with showtimes")
286

287
for cinema in showtimes[:3]:
288
    print(f"Cinema: {cinema['cinema']}")
289
    print(f"Address: {cinema.get('address and contacts', 'N/A')}")
290
    movies_count = len(cinema.get('movies', []))
291
    print(f"Movies showing: {movies_count}")
292
```
293

294
## Special Methods and Utilities
295

296
### Information Set Discovery
297

298
Get available information sets for different object types.
299

300
```python { .api }
301
def get_movie_infoset():
302
    """Get list of available movie information sets."""
303

304
def get_person_infoset():
305
    """Get list of available person information sets."""
306

307
def get_character_infoset():
308
    """Get list of available character information sets."""
309

310
def get_company_infoset():
311
    """Get list of available company information sets."""
312

313
def get_special_methods():
314
    """Get special methods defined by the access system."""
315
```
316

317
**Usage Example:**
318

319
```python
320
from imdb import IMDb
321

322
ia = IMDb()
323

324
# Discover available information sets
325
movie_info = ia.get_movie_infoset()
326
person_info = ia.get_person_infoset()
327

328
print(f"Movie info sets: {movie_info}")
329
print(f"Person info sets: {person_info}")
330

331
# Get special methods available
332
special_methods = ia.get_special_methods()
333
print(f"Special methods: {list(special_methods.keys())}")
334
```
335

336
### URL Configuration
337

338
Configure base URLs for IMDb access.
339

340
```python { .api }
341
def set_imdb_urls(imdbURL_base):
342
    """
343
    Set the URLs used for accessing IMDb site.
344
    
345
    Parameters:
346
    - imdbURL_base: str - Base IMDb URL (e.g., 'https://www.imdb.com/')
347
    """
348
```
349

350
**Usage Example:**
351

352
```python
353
from imdb import IMDb
354

355
ia = IMDb()
356

357
# Set custom IMDb base URL (rarely needed)
358
ia.set_imdb_urls('https://www.imdb.com/')
359

360
# Access configured URLs
361
print(f"Movie URL pattern: {ia.urls['movie_main']}")
362
print(f"Person URL pattern: {ia.urls['person_main']}")
363
```
364

365
## Advanced Search Features
366

367
### Cross-Reference Search
368

369
Search across different IMDb entities using internal search functionality.
370

371
```python
372
from imdb import IMDb
373

374
ia = IMDb()
375

376
# Advanced movie search with multiple criteria
377
movies = ia.search_movie_advanced(
378
    title='Matrix',
379
    adult=False,
380
    results=10,
381
    sort='moviemeter',
382
    sort_dir='asc'
383
)
384

385
print(f"Advanced search found {len(movies)} movies")
386
for movie in movies:
387
    print(f"- {movie['title']} ({movie.get('year', 'N/A')})")
388
```
389

390
### Batch Operations
391

392
Perform operations on multiple objects efficiently:
393

394
```python
395
from imdb import IMDb
396

397
ia = IMDb()
398

399
# Get multiple movies and update them
400
movie_titles = ['The Matrix', 'Inception', 'Interstellar']
401
movies = []
402

403
for title in movie_titles:
404
    search_results = ia.search_movie(title)
405
    if search_results:
406
        movie = search_results[0]
407
        ia.update(movie, info=['main', 'plot'])
408
        movies.append(movie)
409

410
# Process all movies
411
for movie in movies:
412
    print(f"{movie['title']}: {movie.get('rating', 'N/A')}/10")
413
    plot = movie.get('plot', ['No plot available'])[0]
414
    print(f"Plot: {plot[:100]}...\n")
415
```
416

417
## Error Handling and Debugging
418

419
Advanced error handling and debugging capabilities:
420

421
```python
422
from imdb import IMDb, IMDbError, IMDbDataAccessError
423

424
# Create instance with detailed error reporting
425
ia = IMDb(reraiseExceptions=True, loggingLevel=10)  # DEBUG level
426

427
try:
428
    # Operations that might fail
429
    movie = ia.get_movie('invalid_id')
430
except IMDbDataAccessError as e:
431
    print(f"Data access error: {e}")
432
except IMDbError as e:
433
    print(f"General IMDb error: {e}")
434

435
# Check object state after operations
436
movie = ia.search_movie('Test')[0]
437
print(f"Movie current info: {movie.current_info}")
438
print(f"Available keys: {list(movie.keys())}")
439
```