duckduckgo-async-search 1.0.0

Async DuckDuckGo search helper with SERP wrapper + Instant Answer API fallback.

duckduckgo-async-search

A tiny, easy-to-use async wrapper around DuckDuckGo search with best-effort fallbacks.

Why this exists

The popular DuckDuckGo search interfaces (ddgs / legacy duckduckgo-search) are synchronous/blocking by design (network + parsing happen in the calling thread). In async applications (FastAPI, agents, notebooks, concurrent pipelines), calling them directly can block the event loop and slow down unrelated tasks.

This library provides a non-blocking async API:

• You call await DuckDuckGoSearch().top_n_result(...)
• Under the hood, blocking SERP calls run in a background worker thread (via asyncio.to_thread) so the main event loop stays responsive
• Searches can safely run alongside other async tasks

Fallback strategy (best-effort reliability)

DuckDuckGo may rate-limit or intermittently fail depending on IP, region, or network conditions. To improve reliability, searches use a multi-stage approach:

1. Primary: DDGS SERP results (ddgs / legacy duckduckgo-search)

   • Tries multiple backends (default: lite, html, auto)
   • Retries with exponential backoff + jitter (configurable)
   • Returns normalized items (title, url, snippet) with a source tag like ddgs:lite

2. Secondary: DuckDuckGo HTML SERP fallback

   • Fetches and parses the public DuckDuckGo HTML results page
   • No additional third-party dependencies
   • Best-effort parsing (may break if DuckDuckGo changes markup)
   • Returns items with source="ddg_html_fallback"

3. Final fallback: DuckDuckGo Instant Answer API (JSON)

   • More stable and less likely to rate-limit
   • Not a full web SERP, but can return useful links from Results and RelatedTopics
   • Returns items with source="instant_answer_api"

If all strategies fail or return no items, a clear error is raised.

Output

top_n_result() returns List[DuckDuckGoResult], where each item includes:

• title: str
• url: str
• snippet: str (when available)
• source: str (which backend produced the item)

Install

pip install duckduckgo-async-search

Colab:

!pip install duckduckgo-async-search

Requirements

• Python: 3.9 or newer
• Dependencies:
  • httpx>=0.27
  • ddgs>=9.0.0

Note: This library relies on the unofficial ddgs package to fetch DuckDuckGo search results.

DuckDuckGo may apply rate limits or blocking, so occasional retries or empty results are expected.

Dependencies are installed automatically when using:

pip install duckduckgo-async-search

Usage

Jupyter / Colab

from duckduckgo_async_search import top_n_result

async def main():
    items = await top_n_result("World's largest mangrove forest", n=5)
    for item in items:
        print(item.title)
        print(item.url)
        print(item.snippet)
        print(item.source)
        print("-" * 30)

await main()

Python script (.py)

import asyncio
from duckduckgo_async_search import top_n_result

async def main():
    items = await top_n_result("World's largest mangrove forest", n=5)
    for item in items:
        print(item.title, item.url, item.source)

if __name__ == "__main__":
    asyncio.run(main())

Class usage

from duckduckgo_async_search import DuckDuckGoSearch

async def main():
    client = DuckDuckGoSearch(
        request_timeout_s = 20.0,
        ddg_backends = None,   # e.g., ["lite", "html", "auto"]
        ddg_pause_s = 1.0,                   # pause between attempts - 2.0 or 3.0
        ddg_max_attempts = 3,                  # total attempts across all backends
        instant_answer_max_bytes = 2_000_000,
        html_fallback_max_bytes = 2_500_000,
        debug = False
    )
    items = await client.top_n_result("World's longest beach", n=10)
    for item in items:
        print(item.title, item.url, item.source)

await main()

Notes

• SERP wrappers can be rate-limited depending on your IP/network.
• Instant Answer API is more reliable but may not reflect “top web results”.

License

MIT License — free for personal and commercial use, modification, and distribution.

Contributing

Source: https://github.com/AbrarJahin/pip-duckduckgo_async_search