DuckDuckGo Search Node for n8n

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

---

🤔 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

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–50)
safeSearch	options	Moderate	Strict, Moderate, or Off
region	string	us-en	Locale code (e.g. de-de, fr-fr)
useSearchOperators	boolean	false	Enable advanced operator parsing
searchOperators	string	—	Operator string appended to query

Example:

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

Sample output:

[
  {
    "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–50)
safeSearch	options	Moderate	Strict, Moderate, or Off

Example:

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

Sample output:

[
  {
    "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–50)
safeSearch	options	Moderate	Strict, Moderate, or Off
region	string	us-en	Locale code
timePeriod	string	—	Time filter: d (day), w (week), m (month), y (year)

Example:

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

Sample output:

[
  {
    "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.

---

Video Search

Searches DuckDuckGo video results.

Parameters:

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

Example:

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

Sample output:

[
  {
    "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.

---

⚙️ Configuration Reference

Common Parameters (all operations)

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

Operation-specific parameters

Operation	Extra parameters
Web Search	useSearchOperators, searchOperators
News Search	timePeriod (d, w, m, y)
Image Search	(none beyond common)
Video Search	(none beyond common)

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"

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"

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:

{
  "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	zh-cn
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

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

---

🔒 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: The telemetry module is a confirmed no-op. 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: Requests go directly to DuckDuckGo (duckduckgo.com, i.js). No third-party proxies or intermediaries.
• 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.

---

💡 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 file for details.

---

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