Text Search

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]]:
    """
    DuckDuckGo text search. Query params: https://duckduckgo.com/params.

    Parameters:
    - keywords (str): Search keywords/query terms
    - region (str, optional): Region code (us-en, uk-en, ru-ru, etc.). Defaults to None.
    - safesearch (str): Safety filter level ("on", "moderate", "off"). Defaults to "moderate".
    - timelimit (str, optional): Time filter ("d", "w", "m", "y" for day, week, month, year). Defaults to None.
    - backend (str): Search backend ("auto", "html", "lite", "bing"). Defaults to "auto".
        - "auto": Try all backends in random order with fallback
        - "html": Use html.duckduckgo.com backend  
        - "lite": Use lite.duckduckgo.com backend
        - "bing": Use bing.com backend
    - max_results (int, optional): Maximum number of results to return. If None, returns results from first response only. Defaults to None.

    Returns:
    List of dictionaries with search results containing:
    - "title" (str): Result title
    - "href" (str): Result URL  
    - "body" (str): Result description/snippet

    Raises:
    - DuckDuckGoSearchException: Base exception for search errors
    - RatelimitException: API request rate limit exceeded
    - TimeoutException: Request timeout occurred
    """

from duckduckgo_search import DDGS

with DDGS() as ddgs:
    results = ddgs.text("python programming")
    for result in results:
        print(f"Title: {result['title']}")
        print(f"URL: {result['href']}")
        print(f"Summary: {result['body']}")
        print("---")

from duckduckgo_search import DDGS

with DDGS() as ddgs:
    # Search with region, time filter, and result limit
    results = ddgs.text(
        keywords="machine learning tutorials",
        region="us-en",
        safesearch="moderate", 
        timelimit="w",  # Past week
        max_results=10
    )
    
    for result in results:
        print(f"Title: {result['title']}")
        print(f"URL: {result['href']}")
        print("---")

from duckduckgo_search import DDGS

with DDGS() as ddgs:
    # Use specific backend (html in this case)
    results = ddgs.text(
        keywords="data science",
        backend="html",
        max_results=5
    )
    
    for result in results:
        print(f"Found: {result['title']}")
        print(f"Link: {result['href']}")

from duckduckgo_search import DDGS

# Configure with proxy and custom settings
with DDGS(
    proxy="socks5://127.0.0.1:9150",  # Tor proxy
    timeout=30,
    verify=True
) as ddgs:
    results = ddgs.text(
        keywords="secure communications",
        safesearch="on",
        max_results=20
    )
    
    print(f"Found {len(results)} results")
    for result in results:
        print(f"- {result['title']}: {result['href']}")

from duckduckgo_search import DDGS
from duckduckgo_search.exceptions import (
    DuckDuckGoSearchException,
    RatelimitException, 
    TimeoutException
)

try:
    with DDGS() as ddgs:
        results = ddgs.text("test query", max_results=50)
        print(f"Retrieved {len(results)} results")
        
except RatelimitException as e:
    print(f"Rate limit exceeded: {e}")
    # Implement retry logic with backoff
    
except TimeoutException as e:
    print(f"Request timed out: {e}")
    # Retry with different backend or increased timeout
    
except DuckDuckGoSearchException as e:
    print(f"Search error: {e}")
    # Handle other search-related errors