0
# DDGS - Dux Distributed Global Search
1

2
A metasearch library that aggregates results from diverse web search services including Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex, and others. DDGS provides a unified API for text search, image search, video search, news search, and book search across different providers with automatic fallback handling when individual services are unavailable.
3

4
## Package Information
5

6
- **Package Name**: ddgs
7
- **Version**: 9.5.5
8
- **Language**: Python  
9
- **Installation**: `pip install ddgs`
10
- **Requirements**: Python 3.9+
11

12
## Core Imports
13

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

18
Import exceptions:
19

20
```python
21
from ddgs.exceptions import DDGSException, RatelimitException, TimeoutException
22
```
23

24
## Basic Usage
25

26
```python
27
from ddgs import DDGS
28
from ddgs.exceptions import DDGSException, TimeoutException
29

30
# Basic text search
31
with DDGS() as ddgs:
32
    results = ddgs.text("python programming", max_results=10)
33
    for result in results:
34
        print(f"{result['title']} - {result['href']}")
35

36
# Search with specific parameters and error handling
37
try:
38
    with DDGS(timeout=10, proxy=None) as ddgs:
39
        # Text search with region and time filters
40
        results = ddgs.text(
41
            "machine learning",
42
            region="us-en",
43
            safesearch="moderate", 
44
            timelimit="m",  # last month
45
            max_results=20
46
        )
47
        
48
        # Image search
49
        images = ddgs.images("python logo", max_results=5)
50
        
51
        # News search
52
        news = ddgs.news("artificial intelligence", max_results=10)
53
        
54
        # Video search  
55
        videos = ddgs.videos("python tutorial", max_results=5)
56
        
57
        # Book search
58
        books = ddgs.books("python programming", max_results=5)
59
except TimeoutException:
60
    print("Search timed out")
61
except DDGSException as e:
62
    print(f"Search error: {e}")
63
```
64

65
## Architecture
66

67
DDGS uses a distributed search architecture that coordinates multiple search engines:
68

69
- **DDGS Class**: Main coordinator that manages search engines and aggregates results
70
- **Search Engines**: Individual backend implementations (Google, Bing, DuckDuckGo, etc.)
71
- **Result Aggregation**: Deduplication and ranking system for combined results
72
- **Concurrent Execution**: ThreadPoolExecutor for parallel searches across providers
73
- **Fallback Handling**: Automatic failover when individual search services are unavailable
74

75
The library supports both programmatic usage and command-line interface, making it suitable for integration into applications requiring robust search capabilities, research tools, data collection systems, and any use case where diverse search results from multiple sources are needed with built-in resilience against service outages.
76

77
## Capabilities
78

79
### Core Search Methods
80

81
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.
82

83
```python { .api }
84
def text(query: str, **kwargs) -> list[dict[str, Any]]: ...
85
def images(query: str, **kwargs) -> list[dict[str, Any]]: ... 
86
def news(query: str, **kwargs) -> list[dict[str, Any]]: ...
87
def videos(query: str, **kwargs) -> list[dict[str, Any]]: ...
88
def books(query: str, **kwargs) -> list[dict[str, Any]]: ...
89
```
90

91
[Core Search Methods](./core-search.md)
92

93
### Exception Handling
94

95
Exception classes for handling errors during search operations including rate limiting, timeouts, and general API errors.
96

97
```python { .api }
98
class DDGSException(Exception): ...
99
class RatelimitException(DDGSException): ...  
100
class TimeoutException(DDGSException): ...
101
```
102

103
[Exception Handling](./exceptions.md)
104

105
### Command Line Interface
106

107
Complete CLI interface for performing searches from the command line with support for all search types, output formats, and configuration options.
108

109
```bash { .api }
110
ddgs text -q "search query" [OPTIONS]
111
ddgs images -q "image query" [OPTIONS]
112
ddgs news -q "news query" [OPTIONS] 
113
ddgs videos -q "video query" [OPTIONS]
114
ddgs books -q "book query" [OPTIONS]
115
```
116

117
[Command Line Interface](./cli.md)
118

119
### Configuration and Utilities
120

121
Configuration options, proxy support, utility functions, and result processing capabilities.
122

123
```python { .api }
124
class DDGS:
125
    def __init__(proxy=None, timeout=5, verify=True): ...
126
    
127
def json_dumps(obj: Any) -> str: ...
128
def json_loads(obj: str | bytes) -> Any: ...
129
```
130

131
[Configuration and Utilities](./config-utils.md)
132

133
## Types
134

135
```python { .api }
136
# Search result types (returned as dictionaries)
137
TextResult = dict[str, Any]      # {'title': str, 'href': str, 'body': str}
138
ImagesResult = dict[str, Any]    # {'title': str, 'image': str, 'thumbnail': str, 'url': str, ...}
139
NewsResult = dict[str, Any]      # {'date': str, 'title': str, 'body': str, 'url': str, ...}
140
VideosResult = dict[str, Any]    # {'title': str, 'content': str, 'embed_url': str, ...}
141
BooksResult = dict[str, Any]     # {'title': str, 'author': str, 'url': str, ...}
142

143
# Common parameters
144
Region = str                     # Format: "country-language" e.g. "us-en", "de-de"
145
Safesearch = str                # "on" | "moderate" | "off"
146
Timelimit = str                 # "d" | "w" | "m" | "y" or custom date range
147
Backend = str                   # "auto" | "all" | specific engine names
148
```