n8n-nodes-duckduckgo-search/README.md

AI Agent-ready n8n community node for DuckDuckGo search. Search the web, images, news, and videos with no API key required and no outbound telemetry. Optionally fetch and extract the main text of result pages or any URL, and get DuckDuckGo Instant Answers

# DuckDuckGo Search Node for n8n

[![npm version](https://img.shields.io/npm/v/n8n-nodes-duckduckgo-search.svg)](https://www.npmjs.com/package/n8n-nodes-duckduckgo-search)
[![npm downloads](https://img.shields.io/npm/dw/n8n-nodes-duckduckgo-search.svg)](https://www.npmjs.com/package/n8n-nodes-duckduckgo-search)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub release](https://img.shields.io/github/v/release/samnodehi/n8n-nodes-duckduckgo)](https://github.com/samnodehi/n8n-nodes-duckduckgo/releases/latest)
[![Build](https://github.com/samnodehi/n8n-nodes-duckduckgo/actions/workflows/ci.yml/badge.svg)](https://github.com/samnodehi/n8n-nodes-duckduckgo/actions)

An n8n community node for DuckDuckGo search. Search the web, find images, discover news, and explore videos — no API key required, no outbound telemetry.

## ✨ Features

- **Four search types**: Web, Image, News, Video
- **AI Agent compatible**: Works as a tool in n8n AI Agent workflows (`usableAsTool: true`)
- **No API key required**: Completely free, no registration
- **No outbound telemetry**: No analytics or telemetry data sent anywhere — search requests go only to DuckDuckGo
- **Structured output**: Predictable, consistent field names per operation type
- **Fallback resilience**: News and Video searches fall back to an alternative result path on primary failure, with results clearly labeled
- **Specific error messages**: Named errors for VQD token failures, 403 blocks, and web page parser regressions
- **Search operators**: Advanced query syntax for Web Search (`site:`, `filetype:`, `intitle:`, etc.)
- **Region/locale support**: Configure DuckDuckGo locale codes per operation
- **Safe search**: Configurable per operation
- **Optional page content extraction**: Fetch and extract the main text of result pages (Web and News, opt-in), with optional page metadata
- **Extract Page Content operation**: Give any URL → clean main text + metadata (a "read any page" tool for AI Agents)
- **Instant Answer operation**: Direct answers, abstracts, and definitions from DuckDuckGo's free Instant Answer API

---

## 🤔 Why this node?

- **No API key or paid search API required** — uses DuckDuckGo's public search endpoints directly
- **Works as an n8n AI Agent tool** — attach it to any Agent node; no extra setup needed
- **Four search types in one node** — Web, Image, News, and Video from a single, consistent interface
- **Clean JSON output designed for automation** — predictable field names, no noise, easy to wire into downstream nodes
- **Fallback labels for News and Video** — when results come from the fallback path, `isFallback: true` tells you so

---

## 📦 Installation

### Via n8n Interface (recommended)

1. Go to **Settings** → **Community Nodes**
2. Enter: `n8n-nodes-duckduckgo-search`
3. Click **Install**
4. Restart n8n if required

### Via npm

```bash
npm install n8n-nodes-duckduckgo-search
```

---

## 🚀 Quick Start

1. **Add Node**: Drag the **DuckDuckGo Search** node into your workflow
2. **Choose Operation**: Select Web, Image, News, or Video search
3. **Enter Query**: Type your search terms
4. **Set Limits**: Adjust `maxResults` and `safeSearch` as needed
5. **Execute**: Run your workflow

---

## 🔍 Operations

### Web Search

Searches DuckDuckGo and returns organic web results.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | required | Search terms |
| `maxResults` | number | 10 | Number of results (1–100) |
| `safeSearch` | options | Moderate | `Strict`, `Moderate`, or `Off` |
| `region` | string | wt-wt | Locale code (e.g. `de-de`, `fr-fr`) |
| `useSearchOperators` | boolean | false | Enable advanced operator parsing |
| `searchOperators` | string | — | Operator string appended to query |
| `fetchPageContent` | boolean | false | Fetch each result's page and extract its main text (opt-in; see [Page Content Extraction](#-page-content-extraction)) |
| `pageContentMaxResults` | number | 3 | How many top results to fetch content for (when enabled) |
| `pageContentMaxLength` | number | 2000 | Truncate extracted text to N characters (0 = no limit) |
| `pageContentTimeout` | number | 8000 | Per-page fetch timeout in ms |

**Example:**

```json
{
  "operation": "search",
  "query": "open source AI models 2025",
  "webSearchOptions": {
    "maxResults": 10,
    "safeSearch": "moderate",
    "region": "us-en"
  }
}
```

**Sample output:**

```json
[
  {
    "position": 1,
    "title": "Top Open Source AI Models in 2025",
    "description": "A comprehensive overview of the leading open source AI models...",
    "url": "https://example.com/ai-models-2025",
    "hostname": "example.com",
    "sourceType": "web"
  }
]
```

> **Note:** Web Search output does not include `snippet` (removed; use `description` instead) or `favicon` (removed; was always empty).

---

### Image Search

Searches DuckDuckGo images and returns image metadata.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `imageQuery` | string | required | Image search terms |
| `maxResults` | number | 10 | Number of results (1–100) |
| `safeSearch` | options | Moderate | `Strict`, `Moderate`, or `Off` |

**Example:**

```json
{
  "operation": "searchImages",
  "imageQuery": "mountain landscape sunset",
  "imageSearchOptions": {
    "maxResults": 10,
    "safeSearch": "moderate"
  }
}
```

**Sample output:**

```json
[
  {
    "title": "Mountain Sunset Over the Rockies",
    "imageUrl": "https://example.com/images/mountain-sunset.jpg",
    "thumbnailUrl": "https://tse1.mm.bing.net/th?id=...",
    "url": "https://example.com/photography/mountain-sunset",
    "width": 1920,
    "height": 1080,
    "source": "https://example.com/photography/mountain-sunset",
    "sourceType": "image"
  }
]
```

> **Field note:** `imageUrl` is the direct image URL. `url` is the source page URL where the image was found. `thumbnailUrl` is the DuckDuckGo-hosted thumbnail.

---

### News Search

Searches DuckDuckGo news results.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `newsQuery` | string | required | News search terms |
| `maxResults` | number | 10 | Number of results (1–100) |
| `safeSearch` | options | Moderate | `Strict`, `Moderate`, or `Off` |
| `region` | string | wt-wt | Locale code |
| `timePeriod` | string | — | Time filter: `d` (day), `w` (week), `m` (month), `y` (year) |
| `fetchPageContent` | boolean | false | Fetch each article's page and extract its main text (opt-in; see [Page Content Extraction](#-page-content-extraction)) |
| `pageContentMaxResults` | number | 3 | How many top results to fetch content for (when enabled) |
| `pageContentMaxLength` | number | 2000 | Truncate extracted text to N characters (0 = no limit) |
| `pageContentTimeout` | number | 8000 | Per-page fetch timeout in ms |

**Example:**

```json
{
  "operation": "searchNews",
  "newsQuery": "renewable energy breakthrough",
  "newsSearchOptions": {
    "maxResults": 10,
    "safeSearch": "moderate",
    "region": "us-en",
    "timePeriod": "w"
  }
}
```

**Sample output:**

```json
[
  {
    "title": "New Solar Panel Achieves Record Efficiency",
    "description": "Researchers have announced a breakthrough in photovoltaic efficiency...",
    "url": "https://news.example.com/solar-efficiency",
    "imageUrl": "https://news.example.com/images/solar.jpg",
    "date": "2025-05-15T09:00:00.000Z",
    "relativeTime": "2 hours ago",
    "syndicate": "Tech News Daily",
    "isOld": false,
    "isFallback": false,
    "sourceType": "news"
  }
]
```

> **Field note:** `syndicate` is the news source/publisher name. When the fallback path is used, `syndicate` will be `"DuckDuckGo Fallback"` and `isFallback` will be `true`. See [Fallback Behavior](#-fallback-behavior).

---

### Video Search

Searches DuckDuckGo video results.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `videoQuery` | string | required | Video search terms |
| `maxResults` | number | 10 | Number of results (1–100) |
| `safeSearch` | options | Moderate | `Strict`, `Moderate`, or `Off` |
| `region` | string | wt-wt | Locale code |

**Example:**

```json
{
  "operation": "searchVideos",
  "videoQuery": "machine learning tutorial beginners",
  "videoSearchOptions": {
    "maxResults": 10,
    "safeSearch": "moderate"
  }
}
```

**Sample output:**

```json
[
  {
    "title": "Machine Learning Full Course for Beginners",
    "description": "A complete introduction to machine learning concepts...",
    "url": "https://www.youtube.com/watch?v=...",
    "imageUrl": "https://i.ytimg.com/vi/.../hqdefault.jpg",
    "duration": "2:14:30",
    "published": "2024-11-10T00:00:00.000Z",
    "publishedOn": "YouTube",
    "publisher": "FreeCodeCamp",
    "viewCount": "2100000",
    "isFallback": false,
    "sourceType": "video"
  }
]
```

> **Field note:** When the fallback path is used, `publisher` will be `"DuckDuckGo Fallback"` and `isFallback` will be `true`. See [Fallback Behavior](#-fallback-behavior).

---

### Extract Page Content

Fetches **any URL** (not a search) and extracts its main readable text — useful when an AI Agent already has a URL and needs to read the page.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | required | The page URL to fetch and extract |
| `pageContentMaxLength` | number | 2000 | Truncate extracted text to N characters (0 = no limit) |
| `pageContentTimeout` | number | 8000 | Fetch timeout in ms |
| `includePageMetadata` | boolean | false | Also return title/author/published/excerpt/siteName when the page is an article |

**Sample output:**

```json
{
  "url": "https://example.com/article",
  "content": "Extracted main text of the page…",
  "sourceType": "pageContent",
  "title": "Article Title",
  "siteName": "Example"
}
```

> ⚠️ This operation fetches a third-party URL directly (not DuckDuckGo). See [Privacy & Security](#-privacy--security).

---

### Instant Answer

Returns DuckDuckGo's **Instant Answer** for a query — a direct answer, a Wikipedia-style abstract, a definition, and related topics — via the official **free, no-key** API.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `instantAnswerQuery` | string | required | The term or question (e.g. a person, place, or concept) |

**Sample output:**

```json
{
  "query": "DuckDuckGo",
  "heading": "DuckDuckGo",
  "abstract": "DuckDuckGo is an internet search engine that emphasizes protecting searchers' privacy…",
  "abstractSource": "Wikipedia",
  "abstractURL": "https://en.wikipedia.org/wiki/DuckDuckGo",
  "relatedTopics": [
    { "text": "…", "url": "https://duckduckgo.com/…" }
  ],
  "type": "A",
  "sourceType": "instantAnswer"
}
```

> **Note:** Instant Answers exist only for some queries (entities, definitions, calculations). For general queries the fields may be empty — use Web Search instead.

---

## ⚙️ Configuration Reference

### Common Parameters (all operations)

| Parameter | Type | Default | Values |
|-----------|------|---------|--------|
| `maxResults` | number | 10 | 1–100 |
| `safeSearch` | options | Moderate | `Strict`, `Moderate`, `Off` |
| `region` | string | `wt-wt` | DuckDuckGo locale code (e.g. `de-de`, `fr-fr`) |

### Operation-specific parameters

| Operation | Extra parameters |
|-----------|-----------------|
| Web Search | `useSearchOperators`, `searchOperators`, `fetchPageContent` (+ `pageContentMaxResults`, `pageContentMaxLength`, `pageContentTimeout`) |
| News Search | `timePeriod` (`d`, `w`, `m`, `y`), `fetchPageContent` (+ `pageContentMaxResults`, `pageContentMaxLength`, `pageContentTimeout`) |
| Image Search | *(none beyond common)* |
| Video Search | *(none beyond common)* |
| Extract Page Content | `url`, `pageContentMaxLength`, `pageContentTimeout`, `includePageMetadata` |
| Instant Answer | `instantAnswerQuery` |

### Cache Settings

Available on all operations via the **Cache Settings** collection:

| Setting | Type | Default | Range | Description |
|---------|------|---------|-------|-------------|
| `enableCache` | boolean | `true` | — | Cache results in memory to avoid repeated requests for the same query |
| `cacheTTL` | number | `300` | 60–86400 | Time-to-live in seconds before cached results expire |

Cache is in-memory only and is not shared across n8n worker processes or restarts. It is scoped to the running n8n process.

---


## 📋 Output Field Reference

### Web Search

| Field | Type | Description |
|-------|------|-------------|
| `position` | number | Result rank (1-based) |
| `title` | string | Page title |
| `description` | string | Page description / snippet |
| `url` | string | Page URL |
| `hostname` | string | Domain name |
| `sourceType` | string | Always `"web"` |
| `pageContent` | string | Extracted main text of the result page (only when **Fetch Page Content** is enabled; empty for results beyond the fetched top-N) |
| `pageContentTruncated` | boolean | Present and `true` when `pageContent` was cut to `pageContentMaxLength` |
| `pageContentError` | string | Present only when the page could not be fetched/parsed (e.g. `HTTP 403`, `Timed out after 8000ms`) |
| `pageTitle` / `pageAuthor` / `pagePublished` / `pageExcerpt` / `pageSiteName` | string | Page metadata — present only when **Include Page Metadata** is enabled and the page is an article |

### Image Search

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Image title |
| `imageUrl` | string | Direct URL to the image file |
| `thumbnailUrl` | string | DuckDuckGo thumbnail URL |
| `url` | string | Source page where image was found |
| `width` | number | Image width in pixels |
| `height` | number | Image height in pixels |
| `source` | string | Source page URL where the image was found |
| `sourceType` | string | Always `"image"` |

### News Search

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Article title |
| `description` | string | Article excerpt |
| `url` | string | Article URL |
| `imageUrl` | string | Article thumbnail URL |
| `date` | string | Publication date (ISO 8601) |
| `relativeTime` | string | Human-readable relative time (e.g. "2 hours ago") |
| `syndicate` | string | Publisher/source name; `"DuckDuckGo Fallback"` when fallback path was used |
| `isOld` | boolean | Whether DuckDuckGo considers the article old |
| `isFallback` | boolean | `true` if result came from fallback path |
| `sourceType` | string | Always `"news"` |
| `pageContent` | string | Extracted main text of the article page (only when **Fetch Page Content** is enabled; empty for results beyond the fetched top-N) |
| `pageContentTruncated` | boolean | Present and `true` when `pageContent` was cut to `pageContentMaxLength` |
| `pageContentError` | string | Present only when the page could not be fetched/parsed |
| `pageTitle` / `pageAuthor` / `pagePublished` / `pageExcerpt` / `pageSiteName` | string | Page metadata — present only when **Include Page Metadata** is enabled and the page is an article |

### Video Search

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Video title |
| `description` | string | Video description |
| `url` | string | Video page URL |
| `imageUrl` | string | Video thumbnail URL |
| `duration` | string | Video duration (e.g. `"15:30"`) |
| `published` | string | Publication date (ISO 8601) |
| `publishedOn` | string | Platform where published (e.g. `"YouTube"`) |
| `publisher` | string | Channel/creator name; `"DuckDuckGo Fallback"` when fallback path was used |
| `viewCount` | string | View count (as string) |
| `isFallback` | boolean | `true` if result came from fallback path |
| `sourceType` | string | Always `"video"` |

---

## 🔄 Fallback Behavior

**News Search** and **Video Search** use `duck-duck-scrape` as their primary result source.

If the primary path fails (e.g. DuckDuckGo returns a server error or no parseable results), the node automatically attempts an alternative HTML-based fallback search.

When fallback results are returned:

- `isFallback` is `true` on every result item
- For News: `syndicate` is set to `"DuckDuckGo Fallback"`
- For Video: `publisher` is set to `"DuckDuckGo Fallback"`

When primary results are returned normally:

- `isFallback` is `false` on every result item

This allows downstream nodes and AI Agents to detect and handle fallback results differently if needed (e.g. flag lower confidence, re-rank, or discard).

**Web Search** and **Image Search** do not use a two-tier fallback; they use a single direct HTML-based search path.

---

## ⚠️ Error Behavior

The node surfaces specific, actionable error messages rather than generic failures.

### Image Search: VQD token missing

If DuckDuckGo's image search page does not return a valid VQD token (a session token required to query image results), the node throws:

> `DuckDuckGo image search token (VQD) could not be extracted. Image search may be temporarily unavailable. Please try again later.`

No fake or placeholder image URLs are produced. The result item carries the error message.

### Image Search: 403 Forbidden

If the image results endpoint (`i.js`) returns HTTP 403, the node throws:

> `DuckDuckGo image search returned 403 Forbidden. The search token (VQD) may have expired or the request was blocked. Please try again.`

This typically indicates a VQD token expiry or a temporary block by DuckDuckGo.

### Web Search: Parser failure

If `directWebSearch` receives an HTTP 200 response with a large body but cannot parse any result blocks from it (indicating DuckDuckGo may have changed its HTML structure), the node throws an error with this message:

> `DuckDuckGo web search response could not be parsed. The page structure may have changed. Please try again later.`

This is distinct from a genuine no-results response, which returns an empty array without an error.

### Empty results

An empty result array (`[]`) is a valid response when DuckDuckGo genuinely finds no results for the query. This is not an error condition.

---

## 🤖 AI Agent Usage

This node supports `usableAsTool: true`, making it available as a tool inside n8n AI Agent workflows.

**Setup:**

1. Create an **AI Agent** node in your workflow
2. Add **DuckDuckGo Search** as a connected tool
3. Configure the default operation and parameters
4. The agent will invoke the tool autonomously when a search is needed

**Notes for AI Agent use:**

- Output fields are consistent and predictable, suitable for LLM processing
- `isFallback: true` on news/video results signals lower-confidence data to downstream logic
- Specific error messages (VQD missing, 403, parser failure) help agents self-diagnose and retry
- Some older n8n versions may require the environment variable `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true` to expose community nodes as agent tools

---

## 🔍 Search Operators

Advanced query operators are supported for **Web Search** only. Enable `useSearchOperators` and the operator string is appended to the query before being sent to DuckDuckGo.

| Operator | Example | Effect |
|----------|---------|--------|
| `site:` | `site:github.com` | Restrict to a specific site |
| `filetype:` | `filetype:pdf` | Find specific file types |
| `intitle:` | `intitle:"machine learning"` | Match in page titles |
| `inurl:` | `inurl:tutorial` | Match in page URLs |
| `"exact phrase"` | `"transformer architecture"` | Exact phrase match |
| `-exclude` | `python -snake` | Exclude a term |
| `OR` | `cat OR dog` | Either term |

**Example:**

```json
{
  "operation": "search",
  "query": "machine learning",
  "webSearchOptions": {
    "useSearchOperators": true,
    "searchOperators": "site:arxiv.org filetype:pdf"
  }
}
```

---

## 🌍 Supported Regions

Pass a DuckDuckGo locale code as the `region` parameter. The node does not apply a separate language filter — locale code controls both language and region together. Examples:

| Region | Code |
|--------|------|
| United States (English) | `us-en` |
| United Kingdom | `uk-en` |
| Germany | `de-de` |
| France | `fr-fr` |
| Spain | `es-es` |
| Italy | `it-it` |
| Japan | `jp-jp` |
| Brazil (Portuguese) | `br-pt` |
| China | `cn-zh` |
| Russia | `ru-ru` |
| Netherlands | `nl-nl` |

Many locale codes are supported. Use `wt-wt` for no regional bias. Region codes follow the DuckDuckGo `kl` parameter format.

---

## 🔀 Migration Notes

If you are upgrading from an older version of this node, read the following.

### Removed UI options (silently ignored)

The following UI options were removed because they had no effect on execution or were never implemented. **If these fields exist in saved workflow JSON, they are silently ignored at runtime — no workflow changes are required.**

| Removed option | Reason |
|----------------|--------|
| `useApiKey` / API credential | DuckDuckGo has no public Search API; the credential was never read |
| `searchBackend` | Only the direct HTML backend is used; the selector had no dispatch logic |
| `proxySettings` | Proxy configuration was exposed in the UI but never applied at runtime |
| `reliabilitySettings` | The reliability manager was initialised but search calls were never wrapped with retry or circuit-breaker logic |
| Separate `searchFilters` collection | The UI collection was exposed but never read or applied |
| Web Search `timePeriod` | The date-filter parameter was not included in the web search request body |
| Image filter options (`size`, `color`, `type`, `layout`) | The `i.js` filter parameter is undocumented; smoke testing showed unreliable/silent behavior |
| Video filter options (`duration`, `resolution`, `publishedTime`) | Removed with the reliability and filter cleanup |
| Top-level `locale` option | Redundant with each operation's `Region` option; the per-operation Region (or the `wt-wt` default) is used instead |

### Output field changes

| Old field | Status | Replacement |
|-----------|--------|-------------|
| `snippet` (Web Search) | **Removed** | Use `description` — same content |
| `favicon` (Web Search) | **Removed** | Was always an empty string; no replacement needed |

### New output fields

| Field | Operations | Description |
|-------|-----------|-------------|
| `isFallback` | News, Video | `true` when results came from the fallback path |
| `position` | Web | Result rank (1-based) |

### Correct field names (if your workflow used old examples)

The following field names were incorrect in previous documentation. Use the names in the right column:

| Operation | Wrong name (old docs) | Correct name |
|-----------|----------------------|-------------|
| News | `publishedDate` | `date` |
| News | `source` | `syndicate` |
| Video | `thumbnail` | `imageUrl` |
| Video | `publishedDate` | `published` |
| Video | `views` | `viewCount` |
| Video | `source` | `publisher` |
| Image | `thumbnail` | `thumbnailUrl` |

---

## 🆘 Troubleshooting

### Empty results

- Try a broader or simpler query
- Check region/language settings — some queries return fewer results in non-default locales
- Verify safe search settings are not filtering valid results
- DuckDuckGo may temporarily return no results for some queries; retry after a short delay

### Image search fails with VQD error

DuckDuckGo image search requires a session token (VQD) extracted from an initial page load. If this extraction fails, retry the request. This is a temporary DuckDuckGo availability issue.

### Image search fails with 403

The VQD token may have expired or DuckDuckGo has temporarily rate-limited requests from your IP. Wait a short period and retry.

### Web search returns parser failure error

DuckDuckGo may have changed its HTML page structure. This means the node's result extractor cannot parse the page. This is a known fragility of HTML-based scraping. Please open a GitHub issue if this persists.

### News/video results marked `isFallback: true`

The primary search path failed and the fallback HTML path was used. Results are real but may have less metadata (e.g. no relative time or thumbnail). If high-quality metadata is critical, retry or filter on `isFallback: false`.

### Configuration errors

- Verify the query field is not empty
- Ensure `region` uses a valid locale code (e.g. `us-en`, not `en-US`)
- `maxResults` must be between 1 and 50

---

## 📄 Page Content Extraction

By default, Web Search returns DuckDuckGo's short snippet (the `description` field). DuckDuckGo controls that snippet length, and the node already returns all of it.

To get **more text**, enable **Fetch Page Content** (available on **Web Search** and **News Search**, off by default). The node then fetches the actual page behind each of the top results and extracts its main readable text into a `pageContent` field.

| Option | Default | Purpose |
|--------|---------|---------|
| `fetchPageContent` | `false` | Master toggle |
| `pageContentMaxResults` | `3` | Fetch content for the top N results only (controls speed) |
| `pageContentMaxLength` | `2000` | Truncate each `pageContent` to N characters (`0` = no limit) |
| `pageContentTimeout` | `8000` | Per-page fetch timeout in milliseconds |
| `includePageMetadata` | `false` | Also add `pageTitle` / `pageAuthor` / `pagePublished` / `pageExcerpt` / `pageSiteName` (when the page is an article) |

**How it works:** extraction is three-tiered — (1) [Mozilla Readability](https://github.com/mozilla/readability) over a lightweight [linkedom](https://github.com/WebReflection/linkedom) DOM pulls the main article text and drops nav/boilerplate; (2) when Readability finds no article, a DOM heuristic removes boilerplate and high link-density blocks (menus not wrapped in `<nav>`); (3) if DOM parsing fails, a dependency-free regex heuristic is the last resort. The result feeds clean text to downstream nodes or AI agents.

**Important caveats:**

- ⚠️ **Privacy:** when enabled, the node makes HTTP requests to the **third-party result sites** — not only to DuckDuckGo. It is off by default precisely to preserve the DuckDuckGo-only guarantee.
- **Speed:** each fetched result is one extra HTTP request. Keep `pageContentMaxResults` small (default 3) for fast workflows.
- **Resilience:** a page that times out, blocks bots, or returns non-HTML does not fail the search — that result gets an empty `pageContent` and a `pageContentError` instead.
- **JavaScript-rendered sites:** pages that render content client-side return little text from a raw fetch. Extracting those needs a headless browser, which is out of scope for this node.
- **Quality:** Readability handles most article pages cleanly; sites it cannot parse fall back to a DOM/heuristic path that may keep a little navigation text. Page metadata (especially `pageAuthor`) is also extracted heuristically and may occasionally be imprecise. For the highest-quality extraction or summarisation, pipe `pageContent` into a downstream LLM node in your workflow.

**Example:**

```json
{
  "operation": "search",
  "query": "transformer architecture explained",
  "webSearchOptions": {
    "maxResults": 10,
    "fetchPageContent": true,
    "pageContentMaxResults": 3,
    "pageContentMaxLength": 3000
  }
}
```

---

## 🔒 Privacy & Security

- **No API key required**: This node makes direct requests to DuckDuckGo's public search endpoints. No account or API key is needed.
- **No analytics or telemetry**: This node contains no telemetry or analytics code. No query data, result data, or execution metadata is sent to any analytics or telemetry service. Search requests go to DuckDuckGo only.
- **No credentials registered**: The n8n credential registry for this package is empty. n8n will not prompt for any DuckDuckGo credentials.
- **Direct requests only (by default)**: Search requests go directly to DuckDuckGo (`duckduckgo.com`, `html.duckduckgo.com`, `i.js`). No third-party search API, proxy, or intermediary is involved. The one exception is the opt-in Fetch Page Content feature below.
- **Optional page-content fetch (off by default)**: If you enable **Fetch Page Content** (Web or News Search), the node additionally requests each fetched result's page from its own third-party server to extract text. This is the only path that contacts non-DuckDuckGo hosts, and it is disabled unless you turn it on. See [Page Content Extraction](#-page-content-extraction).
- **No disk storage**: The node does not write queries or results to disk. Optional in-memory caching may temporarily keep results for the configured cache TTL (default 5 minutes) within the running n8n process.

---

## 🔌 Backend Architecture

| Operation | Primary path | Fallback path |
|-----------|-------------|---------------|
| Web Search | `directWebSearch` (html.duckduckgo.com POST) | None |
| Image Search | `directImageSearch` (duckduckgo.com + i.js) | None |
| News Search | `duck-duck-scrape` `searchNews` | HTML-based fallback |
| Video Search | `duck-duck-scrape` `searchVideos` | HTML-based fallback |

There is no user-configurable backend selector. Each operation type uses the most reliable path available. Every path — primary and fallback — talks only to DuckDuckGo; no third-party search API is used.

---

## 💡 Use Cases

- **Content research**: Find web pages, images, news, and videos on any topic
- **AI Agent workflows**: Give your AI agent autonomous search capability
- **News monitoring**: Track current events with time-filtered news search
- **Data enrichment**: Add search results to your workflow data
- **Competitive intelligence**: Research competitors, products, or industries
- **Automated content curation**: Build workflows that discover and process fresh content

---

## 🤝 Contributing

This is an open-source project. Contributions are welcome:

- **Bug reports**: Open a GitHub issue with reproduction steps
- **Feature requests**: Describe the use case clearly
- **Pull requests**: Submit against the main branch

---

## 📄 License

MIT License — see the [LICENSE](LICENSE.md) file for details.

---

*Install the node and start searching with DuckDuckGo in your n8n workflows today.*