0
# Core Search Methods
1

2
Fundamental search functionality across five major categories: text, images, news, videos, and books. Each method supports region-specific searches, safety filters, time-limited results, and backend selection with automatic fallback and result aggregation.
3

4
## Capabilities
5

6
### Text Search
7

8
Performs text search across multiple search engines including Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex, and Wikipedia with automatic result ranking and deduplication.
9

10
```python { .api }
11
def text(
12
    query: str,
13
    *,
14
    region: str = "us-en",
15
    safesearch: str = "moderate", 
16
    timelimit: str | None = None,
17
    max_results: int | None = 10,
18
    page: int = 1,
19
    backend: str = "auto",
20
    **kwargs: Any
21
) -> list[dict[str, Any]]:
22
    """
23
    Perform text search across multiple search engines.
24
    
25
    Parameters:
26
    - query: Search query string (required)
27
    - region: Search region in format "country-language" (default: "us-en")
28
    - safesearch: Safety level "on"/"moderate"/"off" (default: "moderate")
29
    - timelimit: Time filter "d"/"w"/"m"/"y" for day/week/month/year (default: None)
30
    - max_results: Maximum number of results to return (default: 10)
31
    - page: Page number for pagination (default: 1)
32
    - backend: Search backend selection (default: "auto")
33
    
34
    Available backends:
35
    - "auto": Automatic backend selection with Wikipedia prioritized first
36
    - "all": All available backends with Wikipedia prioritized first
37
    - "wikipedia": Wikipedia search engine
38
    - "bing": Bing search engine  
39
    - "brave": Brave search engine
40
    - "duckduckgo": DuckDuckGo search engine (currently disabled due to rate limits)
41
    - "google": Google search engine
42
    - "mojeek": Mojeek search engine
43
    - "mullvad_brave": Mullvad Leta via Brave
44
    - "mullvad_google": Mullvad Leta via Google
45
    - "yandex": Yandex search engine
46
    - "yahoo": Yahoo search engine
47
    
48
    Returns:
49
    List of dictionaries with keys:
50
    - title: str - Result title
51
    - href: str - Result URL
52
    - body: str - Result description/snippet
53
    """
54
```
55

56
**Usage Example:**
57

58
```python
59
with DDGS() as ddgs:
60
    # Basic text search
61
    results = ddgs.text("python programming")
62
    
63
    # Advanced text search with filters
64
    results = ddgs.text(
65
        "machine learning tutorials",
66
        region="us-en",
67
        safesearch="moderate",
68
        timelimit="w",  # last week
69
        max_results=20,
70
        backend="google,bing"  # specific backends
71
    )
72
    
73
    for result in results:
74
        print(f"Title: {result['title']}")
75
        print(f"URL: {result['href']}")  
76
        print(f"Description: {result['body']}")
77
        print("-" * 50)
78
```
79

80
### Image Search
81

82
Performs image search with support for size, color, type, layout, and license filtering.
83

84
```python { .api }
85
def images(
86
    query: str,
87
    *,
88
    region: str = "us-en",
89
    safesearch: str = "moderate",
90
    timelimit: str | None = None, 
91
    max_results: int | None = 10,
92
    page: int = 1,
93
    backend: str = "auto",
94
    size: str | None = None,
95
    color: str | None = None,
96
    type_image: str | None = None,
97
    layout: str | None = None,
98
    license_image: str | None = None,
99
    **kwargs: Any
100
) -> list[dict[str, Any]]:
101
    """
102
    Perform image search with filtering options.
103
    
104
    Parameters:
105
    - query: Search query string (required)
106
    - size: Image size "Small"/"Medium"/"Large"/"Wallpaper"
107
    - color: Color filter "color"/"Monochrome"/"Red"/"Orange"/"Yellow"/"Green"/"Blue"/"Purple"/"Pink"/"Brown"/"Black"/"Gray"/"Teal"/"White"
108
    - type_image: Image type "photo"/"clipart"/"gif"/"transparent"/"line"
109
    - layout: Layout preference "Square"/"Tall"/"Wide"
110
    - license_image: License type "any"/"Public"/"Share"/"ShareCommercially"/"Modify"/"ModifyCommercially"
111
    
112
    Available backends: "auto", "all", "duckduckgo"
113
    
114
    Returns:
115
    List of dictionaries with keys:
116
    - title: str - Image title
117
    - image: str - Full-size image URL
118
    - thumbnail: str - Thumbnail image URL  
119
    - url: str - Source page URL
120
    - height: str - Image height in pixels
121
    - width: str - Image width in pixels
122
    - source: str - Image source/domain
123
    """
124
```
125

126
### News Search
127

128
Performs news search across news sources with date filtering and source information.
129

130
```python { .api }
131
def news(
132
    query: str,
133
    *,
134
    region: str = "us-en",
135
    safesearch: str = "moderate",
136
    timelimit: str | None = None,
137
    max_results: int | None = 10, 
138
    page: int = 1,
139
    backend: str = "auto",
140
    **kwargs: Any
141
) -> list[dict[str, Any]]:
142
    """
143
    Perform news search across news sources.
144
    
145
    Available backends: "auto", "all", "duckduckgo", "yahoo"
146
    
147
    Returns:
148
    List of dictionaries with keys:
149
    - date: str - Publication date
150
    - title: str - Article title
151
    - body: str - Article summary/content
152
    - url: str - Article URL
153
    - image: str - Article image URL (if available)
154
    - source: str - News source name
155
    """
156
```
157

158
### Video Search
159

160
Performs video search with resolution, duration, and license filtering.
161

162
```python { .api }
163
def videos(
164
    query: str,
165
    *,
166
    region: str = "us-en", 
167
    safesearch: str = "moderate",
168
    timelimit: str | None = None,
169
    max_results: int | None = 10,
170
    page: int = 1,
171
    backend: str = "auto",
172
    resolution: str | None = None,
173
    duration: str | None = None,
174
    license_videos: str | None = None,
175
    **kwargs: Any
176
) -> list[dict[str, Any]]:
177
    """
178
    Perform video search with filtering options.
179
    
180
    Parameters:
181
    - resolution: Video quality "high"/"standard"
182
    - duration: Video length "short"/"medium"/"long"  
183
    - license_videos: License type "creativeCommon"/"youtube"
184
    
185
    Available backends: "auto", "all", "duckduckgo"
186
    
187
    Returns:
188
    List of dictionaries with keys:
189
    - title: str - Video title
190
    - content: str - Video content description
191
    - description: str - Video description
192
    - duration: str - Video duration
193
    - embed_html: str - HTML embed code
194
    - embed_url: str - Embeddable video URL
195
    - image_token: str - Image token identifier
196
    - images: dict[str, str] - Video thumbnail images
197
    - provider: str - Video provider (YouTube, Vimeo, etc.)
198
    - published: str - Publication date
199
    - publisher: str - Publisher name
200
    - statistics: dict[str, str] - View counts and other stats
201
    - uploader: str - Video uploader name
202
    """
203
```
204

205
### Book Search
206

207
Performs book search across book databases and archives.
208

209
```python { .api }
210
def books(
211
    query: str,
212
    *,
213
    max_results: int | None = 10,
214
    page: int = 1,
215
    backend: str = "auto",
216
    **kwargs: Any
217
) -> list[dict[str, Any]]:
218
    """
219
    Perform book search across book databases.
220
    
221
    Note: Books search does not support region, safesearch, or timelimit filters.
222
    
223
    Available backends: "auto", "all", "annasarchive"
224
    
225
    Returns:
226
    List of dictionaries with keys:
227
    - title: str - Book title
228
    - author: str - Book author(s)
229
    - publisher: str - Publisher name
230
    - info: str - Book information/description
231
    - url: str - Book page URL
232
    - thumbnail: str - Book cover thumbnail URL
233
    """
234
```
235

236
## Common Parameters
237

238
All search methods accept these standard parameters:
239

240
- **query** (str, required): The search query string
241
- **region** (str): Search region in format "country-language" (default: "us-en")
242
- **safesearch** (str): Content filtering level "on"/"moderate"/"off" (default: "moderate")
243
- **timelimit** (str | None): Time-based filtering "d"/"w"/"m"/"y" (default: None)
244
- **max_results** (int | None): Maximum results to return (default: 10)
245
- **page** (int): Page number for pagination (default: 1)
246
- **backend** (str): Backend selection "auto"/"all" or specific engine names (default: "auto")
247

248
## Backend Selection
249

250
You can specify multiple backends using comma-separated values:
251

252
```python
253
# Use specific engines
254
results = ddgs.text("query", backend="google,bing,brave")
255

256
# Use all available engines  
257
results = ddgs.text("query", backend="all")
258

259
# Use automatic selection (recommended)
260
results = ddgs.text("query", backend="auto")  # or omit parameter
261
```
262

263
## Error Handling
264

265
All search methods may raise:
266

267
- **DDGSException**: General API errors
268
- **RatelimitException**: When rate limits are exceeded  
269
- **TimeoutException**: When requests timeout
270

271
```python
272
from ddgs import DDGS, DDGSException, TimeoutException
273

274
try:
275
    with DDGS(timeout=10) as ddgs:
276
        results = ddgs.text("search query")
277
except TimeoutException:
278
    print("Search timed out")
279
except DDGSException as e:
280
    print(f"Search error: {e}")
281
```