DuckDuckGo Search

Search for text using DuckDuckGo's search engine.

Features

• 🔍 Text search functionality with rich results
• 🌍 Region-specific searches
• 🛡️ SafeSearch options
• ⏰ Time-limited searches
• 🔄 Multiple backend support (HTML and Lite)
• 🌐 Proxy support
• 📝 Comprehensive logging
• 🔒 Optional SSL verification
• 🎭 Random User-Agent rotation

Installation

npm install @phukon/duckduckgo-search
# or
pnpm add @phukon/duckduckgo-search

API Reference

DDGS Class Options

| Option | Type | Default | Description | | ------- | ------- | ------- | ------------------------------- | | headers | Object | {} | Custom HTTP headers | | proxy | string | null | Proxy server URL | | timeout | number | 10000 | Request timeout in milliseconds | | verify | boolean | true | Enable/disable SSL verification |

Search Options

| Option | Type | Default | Description | | ---------- | ------ | ---------- | ----------------------------------- | | keywords | string | Required | Search query | | region | string | 'wt-wt' | Region code (e.g. 'us-en', 'uk-en') | | safesearch | string | 'moderate' | SafeSearch level ('on', 'moderate', 'off') | | timelimit | string | null | Time restriction ('d', 'w', 'm', 'y') | | backend | string | 'auto' | Search backend ('auto', 'html', 'lite') | | maxResults | number | null | Maximum results to return |

Usage

Basic Search

import { DDGS } from "@phukon/duckduckgo-search";

const ddgs = new DDGS();
const results = await ddgs.text({
  keywords: "TypeScript tutorial",
  maxResults: 10,
});
console.log(results);

Advanced Options

import { DDGS, type SearchResult } from "@phukon/duckduckgo-search";

const ddgs = new DDGS({
  headers: { "Accept-Language": "en-US,en;q=0.9" },
  proxy: "http://proxy.example.com:8080",
  timeout: 15000,
  verify: false, // Disable SSL verification
});

const results: SearchResult[] = await ddgs.text({
  keywords: "TypeScript tutorial",
  region: "us-en",
  safesearch: "on",
  timelimit: "y", // Past year
  backend: "html",
  maxResults: 25,
});

CommonJS

const { DDGS } = require("@phukon/duckduckgo-search");

const ddgs = new DDGS();
const results = await ddgs.text({ keywords: "hello world" });

Error Handling

All error classes are exported and can be imported directly:

import {
  DDGS,
  DuckDuckGoSearchError,
  RatelimitError,
  TimeoutError,
} from "@phukon/duckduckgo-search";

try {
  const results = await ddgs.text({ keywords: "test" });
} catch (error) {
  if (error instanceof TimeoutError) {
    // Request timed out
  } else if (error instanceof RatelimitError) {
    // Rate limited or CAPTCHA — wait and retry
  } else if (error instanceof DuckDuckGoSearchError) {
    // General search error (base class for all the above)
  }
}

Exported Types

import type {
  SearchResult,
  Region,
  SafeSearch,
  TimeLimit,
  Backend,
} from "@phukon/duckduckgo-search";

Examples

See the examples/ directory for runnable examples covering every feature:

| Example | Feature | | ------- | ------- | | 01-basic-search.ts | Simplest usage | | 02-limit-results.ts | Limiting result count | | 03-region-search.ts | Region-specific results | | 04-safesearch.ts | Content filtering | | 05-time-filter.ts | Time-limited results | | 06-backend-selection.ts | HTML vs Lite backend | | 07-custom-timeout.ts | Timeout configuration | | 08-proxy-support.ts | Proxy routing | | 09-ssl-verification.ts | SSL verification toggle | | 10-custom-headers.ts | Custom HTTP headers | | 11-error-handling.ts | Typed error handling | | 12-all-options.ts | All options combined | | 13-commonjs-usage.cjs | CommonJS require() |

Roadmap

• [x] Implement keyword search with HTML backend
• [x] Random User-Agent rotation with browser impersonation
• [x] Proxy support
• [x] Custom timeout handling
• [x] Region-specific searches
• [x] Comprehensive logging system
• [x] Error handling with custom errors
• [x] SSL verification toggle
• [ ] HTTP client that can impersonate web browsers (TLS fingerprinting)
• [x] Lite backend implementation
• [ ] News search functionality
• [ ] Image search functionality
• [ ] Video search functionality
• [ ] Cookie management
• [x] CI/CD Pipeline
• [ ] Comprehensive test suite
  • [ ] Unit tests
  • [ ] Integration tests
  • [ ] E2E tests

Acknowledgments

Duckduckgo_search takes inspiration from the following projects:

• Duckduckgo_search (original Python implementation)

📢 Disclaimer

This library is not affiliated with DuckDuckGo and is for educational purposes only. It is not intended for commercial use or any purpose that violates DuckDuckGo's Terms of Service. By using this library, you acknowledge that you will not use it in a way that infringes on DuckDuckGo's terms. The official DuckDuckGo website can be found at https://duckduckgo.com.