DuckDuckJS is a performance-oriented, Deno-first meta-search engine library and command-line tool. It provides a unified TypeScript interface to aggregate search results from multiple providers by utilizing efficient HTML fallbacks and internal JSON APIs, bypassing the need for heavy browser automation or complex frontend execution.
The project is currently in a fast-moving beta state. Architectural changes may occur as we expand engine support and server capabilities.
- Modular Engine Architecture: A plug-and-play system for adding or swapping search providers.
- Multi-Media Support: Native handling for Text, Image, Video, and News search results.
- Resilient Scrape Logic: Uses optimized endpoints to minimize rate-limiting and maximize speed.
- Zero-Config CLI: Highly typed interface with support for pretty-printed terminal output or raw JSON for piping.
- Standalone Binaries: Cross-compiled executables for Linux, macOS, and Windows.
Command Line Interface (CLI)
For immediate use without installation, use the Deno runtime:
# Basic text search
deno run --allow-net src/cli.ts "search query"
# Search for images in a specific region
deno run --allow-net src/cli.ts "concept art" -T image -r us-en
# Search news from the past week
deno run --allow-net src/cli.ts "tech headlines" -T news -t wIf you have downloaded a release binary, you can run it directly:
./duckduckjs "search query" --json- -T, --type: text (default), image, video, news
- -p, --page: pagination offset
- -t, --time: time filter (d, w, m, y)
- -r, --region: region code (default: us-en)
- -j, --json: output raw JSON
Library Integration (Developer Guide)
DuckDuckJS uses a strict Object-Oriented approach. All engines extend a base class, ensuring a consistent contract for your applications.
Import the specific engine you need from the library:
import { DuckDuckGoEngine } from "./src/engines/duckduckgo.ts";
import { BraveEngine } from "./src/engines/brave.ts";
const ddg = new DuckDuckGoEngine();
// Execute a standard search
const results = await ddg.search("Deno development", {
timeLimit: "w",
page: 1,
});
// Access media-specific endpoints
const images = await ddg.images("mountain landscapes");The library provides standardized result shapes for all engines:
- TextResult: { type: "text", title, href, body }
- ImageResult: { type: "image", title, image, thumbnail, url, width, height, source }
- VideoResult: { type: "video", title, description, content, duration, publisher }
- NewsResult: { type: "news", date, title, body, url, image, source }
This project is evolving from a simple scraper into a comprehensive search infrastructure tool.
- Base SearchEngine Architecture and Interfaces
- DuckDuckGo Core Implementation (Text, Images, Videos, News)
- Brave Search Engine Implementation
- Multi-platform CLI Tool
- DuckDuckGo AI Chat (Accessing Llama/Claude endpoints)
- Integration of Bing, Google, and Mojeek engines
- Hono-based HTTP/REST Server wrapper
- MCP (Model Context Protocol) Server for AI Agent tooling
Development occurs on the main branch. Stable releases are branched using a Year.Patch format (e.g., 26.0.0, 26.1.0).
To contribute, ensure your code passes the built-in quality checks:
deno fmt
deno lint
deno task test:integration- Inspiration: Architecturally modeled after the Python library ddgs by deedy5.
- Author: Developed and maintained by @overclockedsenku (Raj Dave).
- AI Disclosure: The core logic, reverse-engineering of endpoints, and architectural flow are human-authored. AI was utilized as a pair-programmer for code enhancement, documentation formatting, and JSDoc generation.
Licensed under the Apache License, Version 2.0. Attribution to the original author is required for any redistributed or modified versions of the software.
DuckDuckJS is intended for educational and developmental purposes. Web scraping utilizes undocumented internal APIs which are subject to change without notice. Users are responsible for adhering to the terms of service and rate limits of the respective search providers.