0
# DuckDuckGo Search
1

2
A Python library for searching DuckDuckGo.com across multiple content types including text, images, videos, and news. It provides both programmatic API access through the DDGS class and command-line interface functionality for direct search operations, with support for advanced search features, regional settings, proxy configuration, and bulk download capabilities.
3

4
## Package Information
5

6
- **Package Name**: duckduckgo_search
7
- **Language**: Python
8
- **Installation**: `pip install duckduckgo_search`
9

10
**Note**: This package has been renamed to `ddgs`. When using the DDGS class, a RuntimeWarning will be displayed recommending migration to the newer `ddgs` package via `pip install ddgs`.
11

12
## Core Imports
13

14
```python
15
from duckduckgo_search import DDGS
16
```
17

18
Import version information:
19

20
```python
21
from duckduckgo_search import __version__
22
```
23

24
Import exceptions for error handling:
25

26
```python
27
from duckduckgo_search.exceptions import (
28
    DuckDuckGoSearchException,
29
    RatelimitException, 
30
    TimeoutException,
31
    ConversationLimitException
32
)
33
```
34

35
## Basic Usage
36

37
```python
38
from duckduckgo_search import DDGS
39

40
# Basic text search
41
with DDGS() as ddgs:
42
    results = ddgs.text("python programming", max_results=5)
43
    for result in results:
44
        print(f"Title: {result['title']}")
45
        print(f"URL: {result['href']}")
46
        print(f"Summary: {result['body']}")
47
        print("---")
48

49
# Image search
50
with DDGS() as ddgs:
51
    images = ddgs.images("cats", max_results=10)
52
    for image in images:
53
        print(f"Image URL: {image['image']}")
54
        print(f"Source: {image['url']}")
55
        print("---")
56

57
# News search
58
with DDGS() as ddgs:
59
    news = ddgs.news("AI technology", max_results=5) 
60
    for article in news:
61
        print(f"Title: {article['title']}")
62
        print(f"Date: {article['date']}")
63
        print(f"Source: {article['source']}")
64
        print("---")
65
```
66

67
## Architecture
68

69
The DDGS class serves as the central interface for all search operations:
70

71
- **DDGS**: Main search class supporting context manager protocol for resource management
72
- **Search Methods**: Specialized methods for different content types (text, images, videos, news)  
73
- **Configuration**: Proxy support, SSL verification, custom headers, and timeout settings
74
- **Backend Selection**: Multiple search backends (auto, html, lite, bing) with automatic fallback
75
- **Rate Limiting**: Built-in request rate limiting and error handling
76

77
The library maintains simplicity through minimal dependencies while providing comprehensive search capabilities across DuckDuckGo's various search verticals.
78

79
## Capabilities
80

81
### Text Search
82

83
Performs text-based web searches with support for regional filtering, safe search settings, time-based filtering, and multiple backend options with automatic fallback.
84

85
```python { .api }
86
def text(
87
    keywords: str,
88
    region: str | None = None,
89
    safesearch: str = "moderate", 
90
    timelimit: str | None = None,
91
    backend: str = "auto",
92
    max_results: int | None = None
93
) -> list[dict[str, str]]: ...
94
```
95

96
[Text Search](./text-search.md)
97

98
### Image Search
99

100
Searches for images with comprehensive filtering options including size, color, type, layout, and licensing filters, returning detailed metadata for each result.
101

102
```python { .api }
103
def images(
104
    keywords: str,
105
    region: str = "us-en",
106
    safesearch: str = "moderate",
107
    timelimit: str | None = None,
108
    size: str | None = None,
109
    color: str | None = None, 
110
    type_image: str | None = None,
111
    layout: str | None = None,
112
    license_image: str | None = None,
113
    max_results: int | None = None
114
) -> list[dict[str, str]]: ...
115
```
116

117
[Image Search](./image-search.md)
118

119
### Video Search
120

121
Searches for videos with filtering by resolution, duration, and licensing, returning comprehensive video metadata and source information.
122

123
```python { .api }
124
def videos(
125
    keywords: str,
126
    region: str = "us-en", 
127
    safesearch: str = "moderate",
128
    timelimit: str | None = None,
129
    resolution: str | None = None,
130
    duration: str | None = None,
131
    license_videos: str | None = None,
132
    max_results: int | None = None
133
) -> list[dict[str, str]]: ...
134
```
135

136
[Video Search](./video-search.md)
137

138
### News Search
139

140
Searches for news articles with time-based filtering and regional settings, returning structured news data with publication dates and source information.
141

142
```python { .api }
143
def news(
144
    keywords: str,
145
    region: str = "us-en",
146
    safesearch: str = "moderate", 
147
    timelimit: str | None = None,
148
    max_results: int | None = None
149
) -> list[dict[str, str]]: ...
150
```
151

152
[News Search](./news-search.md)
153

154
### Command Line Interface
155

156
Complete CLI functionality for all search operations with result saving, downloading, and output formatting options.
157

158
```python { .api }
159
# CLI functions from duckduckgo_search.cli module
160
def cli() -> None: ...
161
def safe_entry_point() -> None: ...
162
```
163

164
[Command Line Interface](./cli.md)
165

166
## Types
167

168
```python { .api }
169
class DDGS:
170
    """DuckDuckgo_search class to get search results from duckduckgo.com."""
171
    
172
    def __init__(
173
        self,
174
        headers: dict[str, str] | None = None,
175
        proxy: str | None = None,
176
        proxies: dict[str, str] | str | None = None,  # deprecated
177
        timeout: int | None = 10,
178
        verify: bool = True,
179
    ) -> None: ...
180
    
181
    def __enter__(self) -> DDGS: ...
182
    
183
    def __exit__(
184
        self,
185
        exc_type: type[BaseException] | None = None, 
186
        exc_val: BaseException | None = None,
187
        exc_tb: TracebackType | None = None,
188
    ) -> None: ...
189

190
class DuckDuckGoSearchException(Exception):
191
    """Base exception class for duckduckgo_search."""
192

193
class RatelimitException(DuckDuckGoSearchException):
194
    """Raised for rate limit exceeded errors during API requests."""
195

196
class TimeoutException(DuckDuckGoSearchException):
197
    """Raised for timeout errors during API requests."""
198

199
class ConversationLimitException(DuckDuckGoSearchException):
200
    """Raised for conversation limit during API requests to AI endpoint."""
201
```