# n8n-nodes-websearch

Smart web search node for n8n with **multiple provider fallback**. Automatically tries different search APIs until it gets good results.

## Features

- **Smart Fallback**: Automatically tries providers in sequence until good results are found
- **7 Search Providers**: Tavily, Serper.dev, Exa, Google CSE, Brave Search, SerpApi, DuckDuckGo
- **Dual Validation**: Checks both result count AND quality before accepting results
- **Three Modes**: Auto (smart fallback), Specific provider, or Custom priority order
- **Tool Ready**: Can be used as a tool in AI agent workflows (`usableAsTool: true`)
- **Pure Node.js**: No Python or external dependencies required
- **Modular**: Easy to add/remove providers

## Installation

### From npm
```bash
npm install n8n-nodes-websearch
```

### In n8n
1. Go to **Settings** > **Community Nodes**
2. Enter `n8n-nodes-websearch`
3. Click **Install**

## Provider Priority (Default Order)

| Priority | Provider | Free Tier | Best For |
|----------|----------|-----------|----------|
| 1 | Tavily | 1,000/month | AI-native, LLM-ready results |
| 2 | Serper.dev | 2,500/month | Google SERPs, very fast |
| 3 | Exa | Free tier | Neural/semantic search |
| 4 | Google CSE | 100/day | Reliable, traditional |
| 5 | Brave Search | Free tier | Privacy-first |
| 6 | SerpApi | 100/month | Multi-engine fallback |
| 7 | DuckDuckGo | Unlimited | No API key needed |

## Credentials Setup

Add your API keys in n8n credentials. You only need to configure the providers you want to use:

| Provider | Required Fields | Get API Key |
|----------|-----------------|-------------|
| Tavily | API Key | [tavily.com](https://tavily.com) |
| Serper.dev | API Key | [serper.dev](https://serper.dev) |
| Exa | API Key | [exa.ai](https://exa.ai) |
| Google CSE | API Key + Search Engine ID | [Google Cloud Console](https://console.cloud.google.com) |
| Brave Search | API Key | [brave.com/search/api](https://brave.com/search/api) |
| SerpApi | API Key | [serpapi.com](https://serpapi.com) |
| DuckDuckGo | Enable toggle | No API key needed! |

## Usage

### Auto Mode (Recommended)
The node automatically tries providers in sequence until it finds good results:

1. Checks if each provider is configured (has API key)
2. Tries the search
3. Validates results (minimum count + quality)
4. If not satisfied, tries next provider
5. Returns best results found

### Specific Provider Mode
Force use of a specific provider (useful for testing or when you want specific results).

### Custom Priority
Override the default sequence with your own order:
```
serper,tavily,brave,duckduckgo
```

## Node Options

| Option | Default | Description |
|--------|---------|-------------|
| Max Results | 10 | Maximum results to return |
| Min Results | 3 | Minimum results before trying next provider |
| Region | us | Region code (us, uk, de, fr, in, etc.) |
| Language | en | Language code |
| Safe Search | true | Enable safe search filtering |
| Time Range | all | Filter by time (day, week, month, year, all) |

## Output Format

```json
{
  "query": "example search",
  "success": true,
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "snippet": "Description of the result...",
      "source": "example.com"
    }
  ],
  "provider": "tavily",
  "meta": {
    "totalResults": 10,
    "searchTime": 234,
    "attemptedProviders": [
      { "provider": "tavily", "success": true, "resultCount": 10 }
    ],
    "mode": "auto"
  }
}
```

## Adding New Providers

The node is designed to be modular. To add a new provider:

1. Add entry in `nodes/WebSearch/config/providers.ts`
2. Create provider file in `nodes/WebSearch/providers/`
3. Register in `nodes/WebSearch/providers/index.ts`
4. Add credential fields in `credentials/WebSearchApi.credentials.ts`

## License

MIT

## Author

[sudipta26889](https://github.com/sudipta26889)

## Links

- [GitHub Repository](https://github.com/sudipta26889/n8n-nodes-websearch)
- [npm Package](https://www.npmjs.com/package/n8n-nodes-websearch)
- [Report Issues](https://github.com/sudipta26889/n8n-nodes-websearch/issues)