web-search

# Web Search

Free web search using DuckDuckGo's Instant Answer API. No API key required.

## Quick Start

```bash
# Basic search
cd /home/hxx/clawd/tools && ./web-search.sh "your query"

# Examples
./web-search.sh "what is artificial intelligence"
./web-search.sh "python programming"
./web-search.sh "define recursion"
./web-search.sh "2+2"
```

## Command-Line Options

### Core Options
- `-h, --help` - Display help message with usage examples
- `--format <format>` - Output format: `text`, `markdown`, `plain` (default: `text`)
  - `text`: Colored terminal output (default)
  - `markdown`: Clean markdown format (no ANSI colors)
  - `plain`: Plain text without colors
- `--no-color` - Disable colored output (same as `--format plain`)
- `--max-related <N>` - Control number of related topics to show (default: 5)
- `--quiet` - Minimal output mode (just results, no headers/footer)

### Output to File
Use shell redirection to save results to file:

```bash
# Save to file
./web-search.sh "query" > output.txt

# With markdown format
./web-search.sh --format markdown "query" > results.md

# With no colors for logs
./web-search.sh --no-color "query" > search.log
```

## What It Returns

The tool provides several result types:

- **Answers** - Direct answers for calculations, conversions, weather, etc.
- **Abstracts** - Wikipedia-style summaries with source and URL
- **Definitions** - Word/term definitions
- **Related Topics** - Additional relevant results (configurable, 5 default)

## Best Practices

1. **Be specific** - More specific queries get better instant answers
2. **Try variations** - If no results, rephrase your query
3. **Use for facts** - Definitions, calculations, quick lookups work best
4. **Check URL** - Always provides DuckDuckGo link for full search
5. **Use appropriate format**:
   - Terminal output: `--format text` (colored, default)
   - Documentation: `--format markdown` > file.md`
   - Logs/piping: `--format plain` or `--no-color`

## Limitations

- No full...

# Web Search Tool

DuckDuckGo Instant Answer API client - free web search without API keys.

## API Details

- **Endpoint**: `https://api.duckduckgo.com/`
- **Parameters**:
  - `q` - Search query (URL-encoded)
  - `format=json` - JSON response
  - `no_html=1` - Plain text (no HTML)
  - `skip_disambig=0` - Include disambiguation results

- **Documentation**: https://duckduckgo.com/api
- **Rate Limits**: None documented (be respectful)

## Response Structure

```json
{
  "Abstract": "Full text summary",
  "AbstractSource": "Wikipedia",
  "AbstractURL": "https://...",
  "Answer": "Direct answer (e.g., 4 for 2+2)",
  "AnswerType": "calc",
  "Definition": "Term definition",
  "Heading": "Result title",
  "RelatedTopics": [
    {
      "Text": "Topic description",
      "FirstURL": "https://..."
    }
  ]
}
```

## Query Types That Work Well

1. **Calculations**: `2+2`, `sqrt(144)`, `10% of 500`
2. **Definitions**: `define recursion`, `what is AI`
3. **Conversions**: `100 miles to km`, `50c to fahrenheit`
4. **Facts**: `population of Tokyo`, `who won 2024 Olympics`
5. **Wikipedia**: `quantum physics`, `French Revolution`

## Query Types That Don't Work Well

1. **Full web searches**: Use DuckDuckGo URL provided in output
2. **Recent news**: DuckDuckGo focuses on evergreen content
3. **Personal queries**: Location-specific, user-specific data
4. **Real-time data**: Stock prices, live scores, etc.

## Character Encoding

Some abstracts have Unicode issues in basic parsing (non-ASCII characters garbled).
Install `jq` for cleaner output:
```bash
sudo apt-get install jq  # Ubuntu/Debian
brew install jq          # macOS
```

## Error Handling

- Network timeout → Tool retries once, then reports error
- Empty response → Reports "No results found" with DuckDuckGo URL
- Invalid JSON → Falls back to basic grep parsing
- No curl/wget → Error message recommending installation