or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfig-utils.mdcore-search.mdexceptions.mdindex.md
tile.json

tessl/pypi-ddgs

A metasearch library that aggregates results from diverse web search services

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/ddgs@9.5.x

To install, run

npx @tessl/cli install tessl/pypi-ddgs@9.5.0

index.mddocs/

DDGS - Dux Distributed Global Search

A metasearch library that aggregates results from diverse web search services including Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex, and others. DDGS provides a unified API for text search, image search, video search, news search, and book search across different providers with automatic fallback handling when individual services are unavailable.

Package Information

  • Package Name: ddgs
  • Version: 9.5.5
  • Language: Python
  • Installation: pip install ddgs
  • Requirements: Python 3.9+

Core Imports

from ddgs import DDGS

Import exceptions:

from ddgs.exceptions import DDGSException, RatelimitException, TimeoutException

Basic Usage

from ddgs import DDGS
from ddgs.exceptions import DDGSException, TimeoutException

# Basic text search
with DDGS() as ddgs:
    results = ddgs.text("python programming", max_results=10)
    for result in results:
        print(f"{result['title']} - {result['href']}")

# Search with specific parameters and error handling
try:
    with DDGS(timeout=10, proxy=None) as ddgs:
        # Text search with region and time filters
        results = ddgs.text(
            "machine learning",
            region="us-en",
            safesearch="moderate", 
            timelimit="m",  # last month
            max_results=20
        )
        
        # Image search
        images = ddgs.images("python logo", max_results=5)
        
        # News search
        news = ddgs.news("artificial intelligence", max_results=10)
        
        # Video search  
        videos = ddgs.videos("python tutorial", max_results=5)
        
        # Book search
        books = ddgs.books("python programming", max_results=5)
except TimeoutException:
    print("Search timed out")
except DDGSException as e:
    print(f"Search error: {e}")

Architecture

DDGS uses a distributed search architecture that coordinates multiple search engines:

  • DDGS Class: Main coordinator that manages search engines and aggregates results
  • Search Engines: Individual backend implementations (Google, Bing, DuckDuckGo, etc.)
  • Result Aggregation: Deduplication and ranking system for combined results
  • Concurrent Execution: ThreadPoolExecutor for parallel searches across providers
  • Fallback Handling: Automatic failover when individual search services are unavailable

The library supports both programmatic usage and command-line interface, making it suitable for integration into applications requiring robust search capabilities, research tools, data collection systems, and any use case where diverse search results from multiple sources are needed with built-in resilience against service outages.

Capabilities

Core Search Methods

Fundamental search functionality across five major categories: text, images, news, videos, and books. Each method supports region-specific searches, safety filters, time-limited results, and backend selection.

def text(query: str, **kwargs) -> list[dict[str, Any]]: ...
def images(query: str, **kwargs) -> list[dict[str, Any]]: ... 
def news(query: str, **kwargs) -> list[dict[str, Any]]: ...
def videos(query: str, **kwargs) -> list[dict[str, Any]]: ...
def books(query: str, **kwargs) -> list[dict[str, Any]]: ...

Core Search Methods

Exception Handling

Exception classes for handling errors during search operations including rate limiting, timeouts, and general API errors.

class DDGSException(Exception): ...
class RatelimitException(DDGSException): ...  
class TimeoutException(DDGSException): ...

Exception Handling

Command Line Interface

Complete CLI interface for performing searches from the command line with support for all search types, output formats, and configuration options.

ddgs text -q "search query" [OPTIONS]
ddgs images -q "image query" [OPTIONS]
ddgs news -q "news query" [OPTIONS] 
ddgs videos -q "video query" [OPTIONS]
ddgs books -q "book query" [OPTIONS]

Command Line Interface

Configuration and Utilities

Configuration options, proxy support, utility functions, and result processing capabilities.

class DDGS:
    def __init__(proxy=None, timeout=5, verify=True): ...
    
def json_dumps(obj: Any) -> str: ...
def json_loads(obj: str | bytes) -> Any: ...

Configuration and Utilities

Types

# Search result types (returned as dictionaries)
TextResult = dict[str, Any]      # {'title': str, 'href': str, 'body': str}
ImagesResult = dict[str, Any]    # {'title': str, 'image': str, 'thumbnail': str, 'url': str, ...}
NewsResult = dict[str, Any]      # {'date': str, 'title': str, 'body': str, 'url': str, ...}
VideosResult = dict[str, Any]    # {'title': str, 'content': str, 'embed_url': str, ...}
BooksResult = dict[str, Any]     # {'title': str, 'author': str, 'url': str, ...}

# Common parameters
Region = str                     # Format: "country-language" e.g. "us-en", "de-de"
Safesearch = str                # "on" | "moderate" | "off"
Timelimit = str                 # "d" | "w" | "m" | "y" or custom date range
Backend = str                   # "auto" | "all" | specific engine names