alweil/brave-search

Brave Search (Hybrid Mode)

Web search via Brave Search API with automatic fallback to web scraping. No browser required.

Architecture

| Method | Priority | When Used | |--------|----------|-----------| | API | Primary | Quando a API key é válida e tem orçamento | | Web Scraping | Fallback | Quando API retorna erro (403, 429, limite excedido) |

Scripts

| Script | Purpose | |--------|---------| | brave.js | Híbrido (recomendado) - Tenta API primeiro, fallback para scrape | | search.js | Web scraping puro (original) | | brave-api.js | API puro | | content.js | Extrair conteúdo de URLs específicas |

Quick Start

# Híbrido - automático
./brave.js "javascript async await"

# Com opções
./brave.js "restaurantes sp" -n 10 -c BR -l pt

Search Híbrido

./brave.js "query"              # Basic search (5 results)
./brave.js "query" -n 10        # More results (max 20)
./brave.js "query" -c BR        # Country code (BR, US, etc)
./brave.js "query" -l pt        # Language (pt, en, etc)

Output

📊 Results for: "javascript async await" (5 found via 🔌 API)

--- Result 1 [API] ---
Title: JavaScript Async/Await
Link: https://developer.mozilla.org/...
Snippet: The async function declaration...

--- Result 2 [API] ---
...

Ou se a API falhar:

⚠️  API failed (403: Forbidden), trying web scraping...
📊 Results for: "query" (5 found via 🌐 Scrape)

API Pura

Se quiser garantir uso da API (falha se indisponível):

./brave-api.js "query" -n 10 -c US -l en

Web Scraping Puro

Se quiser garantir uso do scraping:

./search.js "query"                    # Basic
./search.js "query" -n 10              # More results
./search.js "query" --content          # Include page content

Extract Page Content

Extrai conteúdo legível de uma URL:

./content.js https://example.com/article

Setup

Instalar dependências (necessário para web scraping):

npm ci

API Key

A API key está configurada no script. Para usar sua própria key:

export BRAVE_API_KEY="sua-key-aqui"
./brave-api.js "query"

Ou edite a linha no topo de brave-api.js ou brave.js.

When to Use

• Pesquisar documentação ou referências técnicas
• Buscar fatos ou informações atualizadas
• Extrair conteúdo de URLs específicas
• Qualquer busca web sem necessidade de navegador interativo

Diferenças API vs Scrape

| Feature | API | Scrape | |---------|-----|--------| | Velocidade | ⚡ Mais rápido | 🐢 Mais lento | | Confiabilidade | ✅ Estrutura garantida | ⚠️ Pode quebrar se site mudar | | Rate limit | 2000/mês grátis | Ilimitado (mas lento) | | Custo | Grátis até limite | Sempre grátis | | Precisão | ✅ Alta | ✅ Alta |

Troubleshooting

API 403 Forbidden

• API key inválida ou não ativada
• Acesse https://api.search.brave.com para ativar

API 429 Rate Limit

• Limite mensal excedido (2000 queries/mês no plano grátis)
• Script automaticamente cai para scraping

Scraping vazio

• Brave pode ter mudado o HTML
• Use a API como alternativa