0
# Text Search
1

2
Performs comprehensive text-based web searches using DuckDuckGo's search engine with advanced filtering options, regional settings, multiple backend support, and automatic fallback mechanisms for reliable results.
3

4
## Capabilities
5

6
### Text Search Function
7

8
Searches the web for text content using specified keywords with comprehensive filtering and configuration options.
9

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

22
    Parameters:
23
    - keywords (str): Search keywords/query terms
24
    - region (str, optional): Region code (us-en, uk-en, ru-ru, etc.). Defaults to None.
25
    - safesearch (str): Safety filter level ("on", "moderate", "off"). Defaults to "moderate".
26
    - timelimit (str, optional): Time filter ("d", "w", "m", "y" for day, week, month, year). Defaults to None.
27
    - backend (str): Search backend ("auto", "html", "lite", "bing"). Defaults to "auto".
28
        - "auto": Try all backends in random order with fallback
29
        - "html": Use html.duckduckgo.com backend  
30
        - "lite": Use lite.duckduckgo.com backend
31
        - "bing": Use bing.com backend
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 search results containing:
36
    - "title" (str): Result title
37
    - "href" (str): Result URL  
38
    - "body" (str): Result description/snippet
39

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

47
### Usage Examples
48

49
Basic text search:
50

51
```python
52
from duckduckgo_search import DDGS
53

54
with DDGS() as ddgs:
55
    results = ddgs.text("python programming")
56
    for result in results:
57
        print(f"Title: {result['title']}")
58
        print(f"URL: {result['href']}")
59
        print(f"Summary: {result['body']}")
60
        print("---")
61
```
62

63
Text search with filters:
64

65
```python
66
from duckduckgo_search import DDGS
67

68
with DDGS() as ddgs:
69
    # Search with region, time filter, and result limit
70
    results = ddgs.text(
71
        keywords="machine learning tutorials",
72
        region="us-en",
73
        safesearch="moderate", 
74
        timelimit="w",  # Past week
75
        max_results=10
76
    )
77
    
78
    for result in results:
79
        print(f"Title: {result['title']}")
80
        print(f"URL: {result['href']}")
81
        print("---")
82
```
83

84
Text search with specific backend:
85

86
```python
87
from duckduckgo_search import DDGS
88

89
with DDGS() as ddgs:
90
    # Use specific backend (html in this case)
91
    results = ddgs.text(
92
        keywords="data science",
93
        backend="html",
94
        max_results=5
95
    )
96
    
97
    for result in results:
98
        print(f"Found: {result['title']}")
99
        print(f"Link: {result['href']}")
100
```
101

102
Text search with proxy and custom configuration:
103

104
```python
105
from duckduckgo_search import DDGS
106

107
# Configure with proxy and custom settings
108
with DDGS(
109
    proxy="socks5://127.0.0.1:9150",  # Tor proxy
110
    timeout=30,
111
    verify=True
112
) as ddgs:
113
    results = ddgs.text(
114
        keywords="secure communications",
115
        safesearch="on",
116
        max_results=20
117
    )
118
    
119
    print(f"Found {len(results)} results")
120
    for result in results:
121
        print(f"- {result['title']}: {result['href']}")
122
```
123

124
### Error Handling
125

126
Handle common search errors:
127

128
```python
129
from duckduckgo_search import DDGS
130
from duckduckgo_search.exceptions import (
131
    DuckDuckGoSearchException,
132
    RatelimitException, 
133
    TimeoutException
134
)
135

136
try:
137
    with DDGS() as ddgs:
138
        results = ddgs.text("test query", max_results=50)
139
        print(f"Retrieved {len(results)} results")
140
        
141
except RatelimitException as e:
142
    print(f"Rate limit exceeded: {e}")
143
    # Implement retry logic with backoff
144
    
145
except TimeoutException as e:
146
    print(f"Request timed out: {e}")
147
    # Retry with different backend or increased timeout
148
    
149
except DuckDuckGoSearchException as e:
150
    print(f"Search error: {e}")
151
    # Handle other search-related errors
152
```
153

154
## Parameter Details
155

156
### Region Codes
157
Common region codes for localized search results:
158
- `"us-en"`: United States (English)
159
- `"uk-en"`: United Kingdom (English)  
160
- `"au-en"`: Australia (English)
161
- `"ca-en"`: Canada (English)
162
- `"de-de"`: Germany (German)
163
- `"fr-fr"`: France (French)
164
- `"ru-ru"`: Russia (Russian)
165
- `"jp-jp"`: Japan (Japanese)
166
- `"cn-zh"`: China (Chinese)
167

168
### SafeSearch Options
169
- `"on"`: Strict filtering, blocks adult content
170
- `"moderate"`: Moderate filtering (default)
171
- `"off"`: No filtering
172

173
### Time Limits
174
- `"d"`: Past day
175
- `"w"`: Past week  
176
- `"m"`: Past month
177
- `"y"`: Past year
178

179
### Backend Options
180
- `"auto"`: Automatic backend selection with fallback (recommended)
181
- `"html"`: HTML backend (html.duckduckgo.com)
182
- `"lite"`: Lite backend (lite.duckduckgo.com)  
183
- `"bing"`: Bing backend (currently primary backend)
184

185
Note: Backend availability may change. The "auto" option provides the most reliable experience with automatic fallback.