Ddgs

---
name: DDGS Web Search Skill
description: This skill implements web search functionality via the DDGS (Dux
  Distributed Global Search) engine, aggregating results from diverse search
  services to fetch real-time information.
---

# DDGS Web Search Skill
This skill implements web search functionality via the DDGS (Dux Distributed Global Search) engine, aggregating results from diverse search services to fetch real-time information.

## Features
🔍 Privacy-friendly metasearch  
📰 News search support  
🖼️ Image search support  
📹 Video search support  
📚 Books search support  
🌐 Free to use, no API Key required  
🔒 Privacy protection, no user tracking  
⚡ MCP (Model Context Protocol) and API server support  

## Installation
```bash
# Install via uv (Recommended)
uv pip install ddgs

# Or install via pip
pip install ddgs
```

## Quick Start

### 1. Text Search
The most commonly used search method, returning webpage results:
```python
python -c "
from ddgs import DDGS

query = 'your search query'

results = DDGS().text(
    query,
    region='wt-wt',        # Region: cn-zh (China), us-en (US), wt-wt (Global)
    safesearch='moderate', # Safe search: on, moderate, off
    timelimit='m',         # Time range: d (day), w (week), m (month), y (year), None (unlimited)
    max_results=10,        # Maximum number of results
    backend='auto'         # Backends: auto, duckduckgo, brave, bing, etc.
)

for i, r in enumerate(results, 1):
    print(f\"{i}. {r.get('title')}\")
    print(f\"   URL: {r.get('href')}\")
    print(f\"   Snippet: {str(r.get('body'))[:100]}...\n\")
"
```

### 2. News Search
Search for the latest news:
```python
python -c "
from ddgs import DDGS

results = DDGS().news(
    'AI technology',
    region='wt-wt',
    safesearch='moderate',
    timelimit='d',       # d=past 24 hours, w=past week, m=past month
    max_results=10
)

for r in results:
    print(f\"📰 {r.get('title')}\")
    print(f\"   Source: {r.get('source')}\")
    print(f\"   Date: {r.get('date')}\")
    print(f\"   Link: {r.get('url')}\n\")
"
```

### 3. Image Search
Search for image resources:
```python
python -c "
from ddgs import DDGS

results = DDGS().images(
    'cute cats',
    region='wt-wt',
    safesearch='moderate',
    size='Medium',       # Small, Medium, Large, Wallpaper
    type_image='photo',  # photo, clipart, gif, transparent, line
    layout='Square',     # Square, Tall, Wide
    max_results=10
)

for r in results:
    print(f\"🖼️ {r.get('title')}\")
    print(f\"   Image: {r.get('image')}\")
    print(f\"   Thumbnail: {r.get('thumbnail')}\")
    print(f\"   Source: {r.get('source')}\n\")
"
```

### 4. Video Search
Search for video content:
```python
python -c "
from ddgs import DDGS

results = DDGS().videos(
    'Python programming',
    region='wt-wt',
    safesearch='moderate',
    timelimit='w',       # d, w, m
    resolution='high',   # high, standard
    duration='medium',   # short, medium, long
    max_results=10
)

for r in results:
    print(f\"📹 {r.get('title')}\")
    print(f\"   Duration: {r.get('duration', 'N/A')}\")
    print(f\"   Publisher: {r.get('publisher')}\")
    print(f\"   Link: {r.get('content')}\n\")
"
```

### 5. Books Search
Search for books:
```python
python -c "
from ddgs import DDGS

results = DDGS().books(
    'sea wolf jack london',
    max_results=5
)

for r in results:
    print(f\"📚 {r.get('title')}\")
    print(f\"   Author: {r.get('author')}\")
    print(f\"   Publisher: {r.get('publisher')}\")
    print(f\"   Link: {r.get('link')}\n\")
"
```

## Practical Scripts

### Reusable Search Function
```python
python -c "
from ddgs import DDGS

def web_search(query, search_type='text', max_results=5, region='wt-wt', timelimit=None):
    '''
    Execute DDGS search
    
    Args:
        query: Search keyword
        search_type: text, news, images, videos, books
        max_results: Maximum results
        region: Region (cn-zh, us-en, wt-wt)
        timelimit: Time limit (d, w, m, y)
    '''
    ddgs = DDGS()
    if search_type == 'text':
        return list(ddgs.text(query, region=region, timelimit=timelimit, max_results=max_results))
    elif search_type == 'news':
        return list(ddgs.news(query, region=region, timelimit=timelimit, max_results=max_results))
    elif search_type == 'images':
        return list(ddgs.images(query, region=region, max_results=max_results))
    elif search_type == 'videos':
        return list(ddgs.videos(query, region=region, timelimit=timelimit, max_results=max_results))
    elif search_type == 'books':
        return list(ddgs.books(query, max_results=max_results))
    return []

results = web_search('Python 3.12 new features', max_results=5)
print(f'📊 Found {len(results)} results')
"
```

## Parameters Explained

### Region Codes (region)
| Code | Region |
|---|---|
| cn-zh | China |
| us-en | United States |
| uk-en | United Kingdom |
| jp-jp | Japan |
| kr-kr | South Korea |
| wt-wt | Global (No region limit) |

### Time Limit (timelimit)
| Value | Meaning |
|---|---|
| d | Past 24 hours |
| w | Past week |
| m | Past month |
| y | Past year |
| None | No limit |

### Safe Search (safesearch)
| Value | Meaning |
|---|---|
| on | Strict filtering |
| moderate | Moderate filtering (Default) |
| off | Filtering disabled |

## Error Handling & Proxies

### Basic Error Handling
```python
python -c "
from ddgs import DDGS
from ddgs.exceptions import DDGSException

try:
    results = DDGS().text('test query', max_results=5)
    print(f'✅ Search successful, found {len(results)} results')
except DDGSException as e:
    print(f'❌ Search error: {e}')
except Exception as e:
    print(f'❌ Unknown error: {e}')
"
```

### Using Proxies
```python
python -c "
from ddgs import DDGS

# Set proxy (supports http/https/socks5)
proxy = 'http://127.0.0.1:7890'  

results = DDGS(proxy=proxy).text('test query', max_results=5)
print(f'Successfully searched via proxy, found {len(results)} results')
"
```

## FAQ

**Installation Failed?**
```bash
pip install --upgrade pip
pip install ddgs
```

**No Results Found?**
- Check your network connection.
- Try using a proxy.
- Simplify your search query.
- Verify that your region settings are correct.

**Rate Limited?**
- Add a delay between multiple requests (e.g., `import time; time.sleep(1)`).
- Reduce the `max_results` per request.

## Integration & Notes

### Integration Example
```python
# 1. Search with DDGS
python -c "
from ddgs import DDGS
results = DDGS().text('Python async tutorial', max_results=1)
if results:
    print(f\"URL: {results[0].get('href')}\")
"

# 2. Open result with your browser-use tool
browser-use open <url_from_search>
```

**⚠️ Best Practices:**
- **Respect Rate Limits:** Avoid sending a massive volume of requests in a short period.
- **Optimize Results:** Do not request more results than necessary in a single query.
- **Add Delays:** Use `time.sleep()` when executing batch searches.
- **Handle Exceptions:** Always wrap your API calls in `try/except` blocks.
- **Copyright Awareness:** Search results are for reference only; respect the copyright of the indexed content.