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
# 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 -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 -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 -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 -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 -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 -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 -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 -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?
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_resultsper request.
Integration & Notes
Integration Example
# 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/exceptblocks. - Copyright Awareness: Search results are for reference only; respect the copyright of the indexed content.