duckduckgo-search

name	duckduckgo-search
description	Realiza pesquisas na web usando o DuckDuckGo para recuperar informações em tempo real da internet. Use quando o usuário precisar pesquisar eventos atuais, documentação, tutoriais ou qualquer informação que exija recursos de pesquisa na web.
allowed-tools	Bash(duckduckgo-search:*), Bash(python:*), Bash(pip:*), Bash(uv:*)

Skill de Pesquisa Web DuckDuckGo

Esta skill implementa funcionalidade de pesquisa na web através do mecanismo de busca DuckDuckGo, ajudando a obter informações em tempo real.

Funcionalidades

• 🔍 Pesquisa baseada no DuckDuckGo com foco em privacidade
• 📰 Suporte a pesquisa de notícias
• 🖼️ Suporte a pesquisa de imagens
• 📹 Suporte a pesquisa de vídeos
• 🌐 Sem necessidade de API Key, uso gratuito
• 🔒 Proteção de privacidade, sem rastreamento de usuário

Instalação

# Instalação via uv (recomendado)
uv pip install duckduckgo-search

# Ou instalação via pip
pip install duckduckgo-search

Início Rápido

Modo Linha de Comando

# Pesquisa de texto básica
python -c "
from duckduckgo_search import DDGS

with DDGS() as ddgs:
    results = list(ddgs.text('Python tutorial', max_results=5))
    for r in results:
        print(f\"Título: {r['title']}\")
        print(f\"Link: {r['href']}\")
        print(f\"Resumo: {r['body']}\")
        print('---')
"

Tipos de Pesquisa

1. Pesquisa de Texto (Text Search)

A forma mais comum de pesquisa, retornando resultados de páginas web:

python -c "
from duckduckgo_search import DDGS

query = 'sua consulta de pesquisa'

with DDGS() as ddgs:
    results = list(ddgs.text(
        query,
        region='wt-wt',      # Configuração de região: cn-zh(China), us-en(EUA), wt-wt(Global)
        safesearch='moderate', # Pesquisa segura: on, moderate, off
        timelimit='m',       # Intervalo de tempo: d(dia), w(semana), m(mês), y(ano), None(sem limite)
        max_results=10       # Número máximo de resultados
    ))
    
    for i, r in enumerate(results, 1):
        print(f\"{i}. {r['title']}\")
        print(f\"   URL: {r['href']}\")
        print(f\"   Resumo: {r['body'][:100]}...\")
        print()
"

2. Pesquisa de Notícias (News Search)

Pesquisa por notícias recentes:

python -c "
from duckduckgo_search import DDGS

with DDGS() as ddgs:
    results = list(ddgs.news(
        'AI technology',
        region='wt-wt',
        safesearch='moderate',
        timelimit='d',       # d=últimas 24 horas, w=última semana, m=último mês
        max_results=10
    ))
    
    for r in results:
        print(f\"📰 {r['title']}\")
        print(f\"   Fonte: {r['source']}\")
        print(f\"   Data: {r['date']}\")
        print(f\"   Link: {r['url']}\")
        print()
"

3. Pesquisa de Imagem (Image Search)

Pesquisa por recursos de imagem:

python -c "
from duckduckgo_search import DDGS

with DDGS() as ddgs:
    results = list(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['title']}\")
        print(f\"   Imagem: {r['image']}\")
        print(f\"   Miniatura: {r['thumbnail']}\")
        print(f\"   Fonte: {r['source']}\")
        print()
"

4. Pesquisa de Vídeo (Video Search)

Pesquisa por conteúdo de vídeo:

python -c "
from duckduckgo_search import DDGS

with DDGS() as ddgs:
    results = list(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['title']}\")
        print(f\"   Duração: {r.get('duration', 'N/A')}\")
        print(f\"   Fonte: {r['publisher']}\")
        print(f\"   Link: {r['content']}\")
        print()
"

5. Respostas Instantâneas (Instant Answers)

Obtém respostas instantâneas do DuckDuckGo:

python -c "
from duckduckgo_search import DDGS

with DDGS() as ddgs:
    results = ddgs.answers('what is python programming language')
    
    for r in results:
        print(f\"📚 {r['text']}\")
        print(f\"   Fonte: {r.get('url', 'DuckDuckGo')}\")
"

6. Sugestões de Pesquisa (Suggestions)

Obtém sugestões de pesquisa:

python -c "
from duckduckgo_search import DDGS

with DDGS() as ddgs:
    suggestions = list(ddgs.suggestions('python'))
    
    print('🔍 Sugestões de pesquisa:')
    for s in suggestions:
        print(f\"   - {s['phrase']}\")
"

7. Pesquisa de Mapas (Maps Search)

Pesquisa por informações de localização:

python -c "
from duckduckgo_search import DDGS

with DDGS() as ddgs:
    results = list(ddgs.maps(
        'coffee shop',
        place='Beijing, China',
        max_results=10
    ))
    
    for r in results:
        print(f\"📍 {r['title']}\")
        print(f\"   Endereço: {r['address']}\")
        print(f\"   Telefone: {r.get('phone', 'N/A')}\")
        print(f\"   Coordenadas: {r['latitude']}, {r['longitude']}\")
        print()
"

Scripts Úteis

Função de Pesquisa Genérica

Criando um script de pesquisa reutilizável:

python -c "
from duckduckgo_search import DDGS
import json

def web_search(query, search_type='text', max_results=5, region='wt-wt', timelimit=None):
    '''
    Executa pesquisa no DuckDuckGo
    
    Parâmetros:
        query: Palavra-chave de pesquisa
        search_type: Tipo de pesquisa (text, news, images, videos)
        max_results: Número máximo de resultados
        region: Região (cn-zh, us-en, wt-wt)
        timelimit: Limite de tempo (d, w, m, y)
    '''
    with DDGS() as ddgs:
        if search_type == 'text':
            results = list(ddgs.text(query, region=region, timelimit=timelimit, max_results=max_results))
        elif search_type == 'news':
            results = list(ddgs.news(query, region=region, timelimit=timelimit, max_results=max_results))
        elif search_type == 'images':
            results = list(ddgs.images(query, region=region, max_results=max_results))
        elif search_type == 'videos':
            results = list(ddgs.videos(query, region=region, timelimit=timelimit, max_results=max_results))
        else:
            results = []
    
    return results

# Exemplo de uso
query = 'Python 3.12 new features'
results = web_search(query, search_type='text', max_results=5)

print(f'🔍 Pesquisa: {query}')
print(f'📊 Encontrados {len(results)} resultados')
print()

for i, r in enumerate(results, 1):
    print(f\"{i}. {r['title']}\")
    print(f\"   {r['href']}\")
    print(f\"   {r['body'][:150]}...\")
    print()
"

Pesquisar e Salvar Resultados

python -c "
from duckduckgo_search import DDGS
import json
from datetime import datetime

query = 'latest tech news'
output_file = f'search_results_{datetime.now().strftime(\"%Y%m%d_%H%M%S\")}.json'

with DDGS() as ddgs:
    results = list(ddgs.text(query, max_results=10))

# Salvar em arquivo JSON
with open(output_file, 'w', encoding='utf-8') as f:
    json.dump({
        'query': query,
        'timestamp': datetime.now().isoformat(),
        'results': results
    }, f, ensure_ascii=False, indent=2)

print(f'✅ Resultados da pesquisa salvos em: {output_file}')
print(f'📊 Total de {len(results)} resultados')
"

Pesquisa em Lote com Múltiplas Palavras-chave

python -c "
from duckduckgo_search import DDGS
import time

queries = [
    'Python best practices 2024',
    'React vs Vue 2024',
    'AI development tools'
]

all_results = {}

with DDGS() as ddgs:
    for query in queries:
        print(f'🔍 Pesquisando: {query}')
        results = list(ddgs.text(query, max_results=3))
        all_results[query] = results
        print(f'   Encontrados {len(results)} resultados')
        time.sleep(1)  # Evitar requisições muito rápidas

print()
print('=' * 50)
print('📊 Resumo da Pesquisa')
print('=' * 50)

for query, results in all_results.items():
    print(f'\n🔎 {query}:')
    for i, r in enumerate(results, 1):
        print(f\"   {i}. {r['title'][:60]}...\")
"

Explicação dos Parâmetros

Códigos de Região (region)

Código	Região
cn-zh	China
us-en	Estados Unidos
uk-en	Reino Unido
jp-jp	Japão
kr-kr	Coreia do Sul
wt-wt	Global (Sem restrição de região)

Limite de Tempo (timelimit)

Valor	Significado
d	Últimas 24 horas
w	Última semana
m	Último mês
y	Último ano
None	Sem limite

Pesquisa Segura (safesearch)

Valor	Significado
on	Filtragem estrita
moderate	Filtragem moderada (padrão)
off	Filtragem desligada

Tratamento de Erros

python -c "
from duckduckgo_search import DDGS
from duckduckgo_search.exceptions import DuckDuckGoSearchException

try:
    with DDGS() as ddgs:
        results = list(ddgs.text('test query', max_results=5))
        print(f'✅ Pesquisa bem-sucedida, encontrados {len(results)} resultados')
except DuckDuckGoSearchException as e:
    print(f'❌ Erro na pesquisa: {e}')
except Exception as e:
    print(f'❌ Erro desconhecido: {e}')
"

Uso de Proxy

Se precisar usar um proxy:

python -c "
from duckduckgo_search import DDGS

# Configurar proxy
proxy = 'http://127.0.0.1:7890'  # Substitua pelo seu endereço de proxy

with DDGS(proxy=proxy) as ddgs:
    results = list(ddgs.text('test query', max_results=5))
    print(f'Pesquisa via proxy bem-sucedida, encontrados {len(results)} resultados')
"

Perguntas Frequentes

Falha na instalação?

# Certifique-se de que o pip está na versão mais recente
pip install --upgrade pip
pip install duckduckgo-search

# Ou use uv
uv pip install duckduckgo-search

Pesquisa sem resultados?

# Verifique a conexão de rede
# Tente usar um proxy
# Reduza a complexidade das palavras-chave de pesquisa
# Verifique se a configuração de região está correta

Requisições limitadas?

# Adicione atraso entre múltiplas pesquisas
import time
time.sleep(1)  # Aguarde 1 segundo

# Reduza o número de resultados por requisição única
max_results=5  # Em vez de 50

Integração com Outras Ferramentas

Combinar com browser-use para obter conteúdo detalhado

# 1. Primeiro pesquise com DuckDuckGo
python -c "
from duckduckgo_search import DDGS

with DDGS() as ddgs:
    results = list(ddgs.text('Python async tutorial', max_results=1))
    if results:
        url = results[0]['href']
        print(f'URL: {url}')
"

# 2. Use browser-use para abrir e obter conteúdo detalhado
browser-use open <url_from_search>
browser-use state

Observações Importantes

⚠️ Sugestões de Uso:

1. Respeite os limites de frequência: Evite um grande número de requisições em um curto período
2. Defina o número de resultados razoavelmente: Não solicite muitos resultados de uma vez
3. Adicione atraso apropriado: Ao pesquisar em lote, adicione time.sleep() entre as requisições
4. Trate exceções: Sempre adicione código de tratamento de erros
5. Respeite os direitos autorais: Os resultados da pesquisa são apenas para referência, preste atenção aos direitos autorais do conteúdo