tessl/pypi-duckduckgo-search
Search for words, documents, images, news, maps and text translation using the DuckDuckGo.com search engine.
—
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Pending
The risk profile of this skill
index.mddocs/
DuckDuckGo Search
A Python library for searching DuckDuckGo.com across multiple content types including text, images, videos, and news. It provides both programmatic API access through the DDGS class and command-line interface functionality for direct search operations, with support for advanced search features, regional settings, proxy configuration, and bulk download capabilities.
Package Information
- Package Name: duckduckgo_search
- Language: Python
- Installation:
pip install duckduckgo_search
Note: This package has been renamed to ddgs. When using the DDGS class, a RuntimeWarning will be displayed recommending migration to the newer ddgs package via pip install ddgs.
Core Imports
from duckduckgo_search import DDGSImport version information:
from duckduckgo_search import __version__Import exceptions for error handling:
from duckduckgo_search.exceptions import (
DuckDuckGoSearchException,
RatelimitException,
TimeoutException,
ConversationLimitException
)Basic Usage
from duckduckgo_search import DDGS
# Basic text search
with DDGS() as ddgs:
results = ddgs.text("python programming", max_results=5)
for result in results:
print(f"Title: {result['title']}")
print(f"URL: {result['href']}")
print(f"Summary: {result['body']}")
print("---")
# Image search
with DDGS() as ddgs:
images = ddgs.images("cats", max_results=10)
for image in images:
print(f"Image URL: {image['image']}")
print(f"Source: {image['url']}")
print("---")
# News search
with DDGS() as ddgs:
news = ddgs.news("AI technology", max_results=5)
for article in news:
print(f"Title: {article['title']}")
print(f"Date: {article['date']}")
print(f"Source: {article['source']}")
print("---")Architecture
The DDGS class serves as the central interface for all search operations:
- DDGS: Main search class supporting context manager protocol for resource management
- Search Methods: Specialized methods for different content types (text, images, videos, news)
- Configuration: Proxy support, SSL verification, custom headers, and timeout settings
- Backend Selection: Multiple search backends (auto, html, lite, bing) with automatic fallback
- Rate Limiting: Built-in request rate limiting and error handling
The library maintains simplicity through minimal dependencies while providing comprehensive search capabilities across DuckDuckGo's various search verticals.
Capabilities
Text Search
Performs text-based web searches with support for regional filtering, safe search settings, time-based filtering, and multiple backend options with automatic fallback.
def text(
keywords: str,
region: str | None = None,
safesearch: str = "moderate",
timelimit: str | None = None,
backend: str = "auto",
max_results: int | None = None
) -> list[dict[str, str]]: ...Image Search
Searches for images with comprehensive filtering options including size, color, type, layout, and licensing filters, returning detailed metadata for each result.
def images(
keywords: str,
region: str = "us-en",
safesearch: str = "moderate",
timelimit: str | None = None,
size: str | None = None,
color: str | None = None,
type_image: str | None = None,
layout: str | None = None,
license_image: str | None = None,
max_results: int | None = None
) -> list[dict[str, str]]: ...Video Search
Searches for videos with filtering by resolution, duration, and licensing, returning comprehensive video metadata and source information.
def videos(
keywords: str,
region: str = "us-en",
safesearch: str = "moderate",
timelimit: str | None = None,
resolution: str | None = None,
duration: str | None = None,
license_videos: str | None = None,
max_results: int | None = None
) -> list[dict[str, str]]: ...News Search
Searches for news articles with time-based filtering and regional settings, returning structured news data with publication dates and source information.
def news(
keywords: str,
region: str = "us-en",
safesearch: str = "moderate",
timelimit: str | None = None,
max_results: int | None = None
) -> list[dict[str, str]]: ...Command Line Interface
Complete CLI functionality for all search operations with result saving, downloading, and output formatting options.
# CLI functions from duckduckgo_search.cli module
def cli() -> None: ...
def safe_entry_point() -> None: ...Types
class DDGS:
"""DuckDuckgo_search class to get search results from duckduckgo.com."""
def __init__(
self,
headers: dict[str, str] | None = None,
proxy: str | None = None,
proxies: dict[str, str] | str | None = None, # deprecated
timeout: int | None = 10,
verify: bool = True,
) -> None: ...
def __enter__(self) -> DDGS: ...
def __exit__(
self,
exc_type: type[BaseException] | None = None,
exc_val: BaseException | None = None,
exc_tb: TracebackType | None = None,
) -> None: ...
class DuckDuckGoSearchException(Exception):
"""Base exception class for duckduckgo_search."""
class RatelimitException(DuckDuckGoSearchException):
"""Raised for rate limit exceeded errors during API requests."""
class TimeoutException(DuckDuckGoSearchException):
"""Raised for timeout errors during API requests."""
class ConversationLimitException(DuckDuckGoSearchException):
"""Raised for conversation limit during API requests to AI endpoint."""