0
# Video Search
1

2
Searches for videos using DuckDuckGo's video search with filtering options for resolution, duration, and licensing, returning comprehensive video metadata and source information.
3

4
## Capabilities
5

6
### Video Search Function
7

8
Searches for videos using specified keywords with filtering and configuration options.
9

10
```python { .api }
11
def videos(
12
    keywords: str,
13
    region: str = "us-en",
14
    safesearch: str = "moderate",
15
    timelimit: str | None = None,
16
    resolution: str | None = None,
17
    duration: str | None = None,
18
    license_videos: str | None = None,
19
    max_results: int | None = None,
20
) -> list[dict[str, str]]:
21
    """
22
    DuckDuckGo videos search. Query params: https://duckduckgo.com/params.
23

24
    Parameters:
25
    - keywords (str): Search keywords/query terms
26
    - region (str): Region code (us-en, uk-en, ru-ru, etc.). Defaults to "us-en".
27
    - safesearch (str): Safety filter level ("on", "moderate", "off"). Defaults to "moderate".
28
    - timelimit (str, optional): Time filter ("d", "w", "m" for day, week, month). Defaults to None.
29
    - resolution (str, optional): Video resolution filter ("high", "standart"). Defaults to None.
30
    - duration (str, optional): Duration filter ("short", "medium", "long"). Defaults to None.
31
    - license_videos (str, optional): License filter ("creativeCommon", "youtube"). Defaults to None.
32
    - max_results (int, optional): Maximum number of results to return. If None, returns results from first response only. Defaults to None.
33

34
    Returns:
35
    List of dictionaries with video search results containing video metadata
36

37
    Raises:
38
    - DuckDuckGoSearchException: Base exception for search errors
39
    - RatelimitException: API request rate limit exceeded  
40
    - TimeoutException: Request timeout occurred
41
    """
42
```
43

44
### Usage Examples
45

46
Basic video search:
47

48
```python
49
from duckduckgo_search import DDGS
50

51
with DDGS() as ddgs:
52
    videos = ddgs.videos("python tutorial")
53
    for video in videos:
54
        print(f"Video content: {video.get('content', 'N/A')}")
55
        # Print all available fields
56
        for key, value in video.items():
57
            print(f"  {key}: {value}")
58
        print("---")
59
```
60

61
Video search with filters:
62

63
```python
64
from duckduckgo_search import DDGS
65

66
with DDGS() as ddgs:
67
    # Search for high-quality, recent videos
68
    videos = ddgs.videos(
69
        keywords="machine learning explained",
70
        region="us-en", 
71
        safesearch="moderate",
72
        timelimit="w",  # Past week
73
        resolution="high",
74
        duration="medium",  # Medium-length videos
75
        max_results=10
76
    )
77
    
78
    for video in videos:
79
        print(f"Video: {video.get('content', 'N/A')}")
80
        print("Available data:")
81
        for key, value in video.items():
82
            print(f"  {key}: {value}")
83
        print("---")
84
```
85

86
Video search with Creative Commons licensing:
87

88
```python
89
from duckduckgo_search import DDGS
90

91
with DDGS() as ddgs:
92
    # Search for Creative Commons licensed videos
93
    videos = ddgs.videos(
94
        keywords="nature documentary",
95
        license_videos="creativeCommon",
96
        resolution="high",
97
        duration="long",
98
        max_results=15
99
    )
100
    
101
    for video in videos:
102
        print(f"Creative Commons Video: {video.get('content', 'N/A')}")
103
        for key, value in video.items():
104
            print(f"  {key}: {value}")
105
        print("---")
106
```
107

108
Video search with error handling:
109

110
```python
111
from duckduckgo_search import DDGS
112
from duckduckgo_search.exceptions import (
113
    DuckDuckGoSearchException,
114
    RatelimitException,
115
    TimeoutException
116
)
117

118
try:
119
    with DDGS() as ddgs:
120
        videos = ddgs.videos(
121
            keywords="cooking tutorial",
122
            duration="short", 
123
            max_results=20
124
        )
125
        
126
        print(f"Retrieved {len(videos)} videos")
127
        
128
        for i, video in enumerate(videos, 1):
129
            print(f"\nVideo {i}:")
130
            for key, value in video.items():
131
                print(f"  {key}: {value}")
132
                
133
except RatelimitException as e:
134
    print(f"Rate limit exceeded: {e}")
135
    
136
except TimeoutException as e:
137
    print(f"Request timed out: {e}")
138
    
139
except DuckDuckGoSearchException as e:
140
    print(f"Video search error: {e}")
141
```
142

143
Regional video search:
144

145
```python
146
from duckduckgo_search import DDGS
147

148
with DDGS() as ddgs:
149
    # Search for videos in different regions  
150
    regions = ["us-en", "uk-en", "au-en", "de-de"]
151
    
152
    for region in regions:
153
        print(f"\nSearching in region: {region}")
154
        videos = ddgs.videos(
155
            keywords="local news",
156
            region=region,
157
            timelimit="d",  # Past day
158
            max_results=3
159
        )
160
        
161
        for video in videos:
162
            print(f"  Video: {video.get('content', 'N/A')}")
163
```
164

165
### Advanced Usage
166

167
Filter and process video results:
168

169
```python
170
from duckduckgo_search import DDGS
171

172
with DDGS() as ddgs:
173
    videos = ddgs.videos("data science", max_results=50)
174
    
175
    # Filter videos by content availability
176
    valid_videos = [v for v in videos if 'content' in v and v['content']]
177
    print(f"Found {len(valid_videos)} videos with content data")
178
    
179
    # Group by unique content (remove duplicates)
180
    unique_videos = {}
181
    for video in valid_videos:
182
        content_key = video.get('content', '')
183
        if content_key and content_key not in unique_videos:
184
            unique_videos[content_key] = video
185
    
186
    print(f"Unique videos: {len(unique_videos)}")
187
    
188
    # Display unique videos
189
    for video in unique_videos.values():
190
        print(f"Video: {video.get('content', 'N/A')}")
191
        for key, value in video.items():
192
            print(f"  {key}: {value}")
193
        print("---")
194
```
195

196
## Parameter Details
197

198
### Time Limits
199
- `"d"`: Past day
200
- `"w"`: Past week
201
- `"m"`: Past month
202

203
### Resolution Options
204
- `"high"`: High definition videos
205
- `"standart"`: Standard definition videos (note: spelling as per API)
206

207
### Duration Options  
208
- `"short"`: Short videos (typically under 4 minutes)
209
- `"medium"`: Medium-length videos (typically 4-20 minutes)
210
- `"long"`: Long videos (typically over 20 minutes)
211

212
### License Options
213
- `"creativeCommon"`: Creative Commons licensed videos
214
- `"youtube"`: YouTube-specific licensing
215

216
### SafeSearch Options
217
- `"on"`: Strict filtering, blocks adult content
218
- `"moderate"`: Moderate filtering (default)
219
- `"off"`: No filtering
220

221
### Region Codes
222
Common region codes for localized video search results:
223
- `"us-en"`: United States (English)
224
- `"uk-en"`: United Kingdom (English)
225
- `"au-en"`: Australia (English)
226
- `"ca-en"`: Canada (English)
227
- `"de-de"`: Germany (German)
228
- `"fr-fr"`: France (French)
229
- `"ru-ru"`: Russia (Russian)
230
- `"jp-jp"`: Japan (Japanese)
231

232
## Result Data Structure
233

234
Video search results are returned as dictionaries containing video metadata. The exact structure may vary, but typically includes:
235

236
- Video content/description information
237
- Source platform details
238
- Metadata about duration, quality, etc.
239

240
Since the video search returns platform-specific metadata, it's recommended to iterate through all available fields in each result to access the complete data set, as shown in the usage examples above.