DDGS Web Search Skill\r

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.\r \r

Features\r

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

Installation\r

# Install via uv (Recommended)\r
uv pip install ddgs\r
\r
# Or install via pip\r
pip install ddgs\r
```\r
\r
## Quick Start\r
\r
### 1. Text Search\r
The most commonly used search method, returning webpage results:\r
```python\r
python -c "\r
from ddgs import DDGS\r
\r
query = 'your search query'\r
\r
results = DDGS().text(\r
    query,\r
    region='wt-wt',        # Region: cn-zh (China), us-en (US), wt-wt (Global)\r
    safesearch='moderate', # Safe search: on, moderate, off\r
    timelimit='m',         # Time range: d (day), w (week), m (month), y (year), None (unlimited)\r
    max_results=10,        # Maximum number of results\r
    backend='auto'         # Backends: auto, duckduckgo, brave, bing, etc.\r
)\r
\r
for i, r in enumerate(results, 1):\r
    print(f\"{i}. {r.get('title')}\")\r
    print(f\"   URL: {r.get('href')}\")\r
    print(f\"   Snippet: {str(r.get('body'))[:100]}...\
\")\r
"\r
```\r
\r
### 2. News Search\r
Search for the latest news:\r
```python\r
python -c "\r
from ddgs import DDGS\r
\r
results = DDGS().news(\r
    'AI technology',\r
    region='wt-wt',\r
    safesearch='moderate',\r
    timelimit='d',       # d=past 24 hours, w=past week, m=past month\r
    max_results=10\r
)\r
\r
for r in results:\r
    print(f\"📰 {r.get('title')}\")\r
    print(f\"   Source: {r.get('source')}\")\r
    print(f\"   Date: {r.get('date')}\")\r
    print(f\"   Link: {r.get('url')}\
\")\r
"\r
```\r
\r
### 3. Image Search\r
Search for image resources:\r
```python\r
python -c "\r
from ddgs import DDGS\r
\r
results = DDGS().images(\r
    'cute cats',\r
    region='wt-wt',\r
    safesearch='moderate',\r
    size='Medium',       # Small, Medium, Large, Wallpaper\r
    type_image='photo',  # photo, clipart, gif, transparent, line\r
    layout='Square',     # Square, Tall, Wide\r
    max_results=10\r
)\r
\r
for r in results:\r
    print(f\"🖼️ {r.get('title')}\")\r
    print(f\"   Image: {r.get('image')}\")\r
    print(f\"   Thumbnail: {r.get('thumbnail')}\")\r
    print(f\"   Source: {r.get('source')}\
\")\r
"\r
```\r
\r
### 4. Video Search\r
Search for video content:\r
```python\r
python -c "\r
from ddgs import DDGS\r
\r
results = DDGS().videos(\r
    'Python programming',\r
    region='wt-wt',\r
    safesearch='moderate',\r
    timelimit='w',       # d, w, m\r
    resolution='high',   # high, standard\r
    duration='medium',   # short, medium, long\r
    max_results=10\r
)\r
\r
for r in results:\r
    print(f\"📹 {r.get('title')}\")\r
    print(f\"   Duration: {r.get('duration', 'N/A')}\")\r
    print(f\"   Publisher: {r.get('publisher')}\")\r
    print(f\"   Link: {r.get('content')}\
\")\r
"\r
```\r
\r
### 5. Books Search\r
Search for books:\r
```python\r
python -c "\r
from ddgs import DDGS\r
\r
results = DDGS().books(\r
    'sea wolf jack london',\r
    max_results=5\r
)\r
\r
for r in results:\r
    print(f\"📚 {r.get('title')}\")\r
    print(f\"   Author: {r.get('author')}\")\r
    print(f\"   Publisher: {r.get('publisher')}\")\r
    print(f\"   Link: {r.get('link')}\
\")\r
"\r
```\r
\r
## Practical Scripts\r
\r
### Reusable Search Function\r
```python\r
python -c "\r
from ddgs import DDGS\r
\r
def web_search(query, search_type='text', max_results=5, region='wt-wt', timelimit=None):\r
    '''\r
    Execute DDGS search\r
    \r
    Args:\r
        query: Search keyword\r
        search_type: text, news, images, videos, books\r
        max_results: Maximum results\r
        region: Region (cn-zh, us-en, wt-wt)\r
        timelimit: Time limit (d, w, m, y)\r
    '''\r
    ddgs = DDGS()\r
    if search_type == 'text':\r
        return list(ddgs.text(query, region=region, timelimit=timelimit, max_results=max_results))\r
    elif search_type == 'news':\r
        return list(ddgs.news(query, region=region, timelimit=timelimit, max_results=max_results))\r
    elif search_type == 'images':\r
        return list(ddgs.images(query, region=region, max_results=max_results))\r
    elif search_type == 'videos':\r
        return list(ddgs.videos(query, region=region, timelimit=timelimit, max_results=max_results))\r
    elif search_type == 'books':\r
        return list(ddgs.books(query, max_results=max_results))\r
    return []\r
\r
results = web_search('Python 3.12 new features', max_results=5)\r
print(f'📊 Found {len(results)} results')\r
"\r
```\r
\r
## Parameters Explained\r
\r
### Region Codes (region)\r
| Code | Region |\r
|---|---|\r
| cn-zh | China |\r
| us-en | United States |\r
| uk-en | United Kingdom |\r
| jp-jp | Japan |\r
| kr-kr | South Korea |\r
| wt-wt | Global (No region limit) |\r
\r
### Time Limit (timelimit)\r
| Value | Meaning |\r
|---|---|\r
| d | Past 24 hours |\r
| w | Past week |\r
| m | Past month |\r
| y | Past year |\r
| None | No limit |\r
\r
### Safe Search (safesearch)\r
| Value | Meaning |\r
|---|---|\r
| on | Strict filtering |\r
| moderate | Moderate filtering (Default) |\r
| off | Filtering disabled |\r
\r
## Error Handling & Proxies\r
\r
### Basic Error Handling\r
```python\r
python -c "\r
from ddgs import DDGS\r
from ddgs.exceptions import DDGSException\r
\r
try:\r
    results = DDGS().text('test query', max_results=5)\r
    print(f'✅ Search successful, found {len(results)} results')\r
except DDGSException as e:\r
    print(f'❌ Search error: {e}')\r
except Exception as e:\r
    print(f'❌ Unknown error: {e}')\r
"\r
```\r
\r
### Using Proxies\r
```python\r
python -c "\r
from ddgs import DDGS\r
\r
# Set proxy (supports http/https/socks5)\r
proxy = 'http://127.0.0.1:7890'  \r
\r
results = DDGS(proxy=proxy).text('test query', max_results=5)\r
print(f'Successfully searched via proxy, found {len(results)} results')\r
"\r
```\r
\r
## FAQ\r
\r
**Installation Failed?**\r
```bash\r
pip install --upgrade pip\r
pip install ddgs\r
```\r
\r
**No Results Found?**\r
- Check your network connection.\r
- Try using a proxy.\r
- Simplify your search query.\r
- Verify that your region settings are correct.\r
\r
**Rate Limited?**\r
- Add a delay between multiple requests (e.g., `import time; time.sleep(1)`).\r
- Reduce the `max_results` per request.\r
\r
## Integration & Notes\r
\r
### Integration Example\r
```python\r
# 1. Search with DDGS\r
python -c "\r
from ddgs import DDGS\r
results = DDGS().text('Python async tutorial', max_results=1)\r
if results:\r
    print(f\"URL: {results[0].get('href')}\")\r
"\r
\r
# 2. Open result with your browser-use tool\r
browser-use open \x3Curl_from_search>\r
```\r
\r
**⚠️ Best Practices:**\r
- **Respect Rate Limits:** Avoid sending a massive volume of requests in a short period.\r
- **Optimize Results:** Do not request more results than necessary in a single query.\r
- **Add Delays:** Use `time.sleep()` when executing batch searches.\r
- **Handle Exceptions:** Always wrap your API calls in `try/except` blocks.\r
- **Copyright Awareness:** Search results are for reference only; respect the copyright of the indexed content.