Overview

The Web Search Service provides a lightweight, clean interface to perform web searches and retrieve relevant URLs. The service extracts search results from DuckDuckGo, processes them to obtain clean, direct URLs, and returns organized results with titles and snippets.

Endpoints

Web Search

The search endpoint performs web searches and returns relevant URLs with titles and snippets.

API Endpoint

Endpoint Parameters

Here is an overview of the parameters that are used by the search endpoint.

Request

query (string, required)

The search query text to find relevant web results.

max_results (integer, optional)

Maximum number of search results to return. Default is 10.

Response

status (string)

Status of the search operation (success or error).

result (array)

Array of search results, each containing:

• url (string): Clean, direct URL of the search result
• title (string): Title of the webpage
• snippet (string): Brief description or excerpt from the webpage

metadata (object)

Search metadata information:

• processed_at (number): Timestamp of when the search was processed
• query (string): The original search query
• result_count (integer): Number of results returned
• instance_id (string): Service instance identifier

error (string)

Error message if status is 'error'.

Examples

Below are examples demonstrating different ways to use the web search service.

Basic Search Request

Response

Limited Results Search Request

Response

Error Response

Technical Details

URL Cleaning

The service automatically cleans and processes URLs from search results:

DuckDuckGo Redirect Format:

Cleaned URL Format:

The service handles:

• URL decoding of encoded characters
• Proper scheme (https://) addition when needed
• Extraction of the actual destination URL from redirects

Best Practices

Query Formulation

• Use clear, specific search terms
• Include relevant keywords
• Consider using quotes for exact phrases
• Keep queries under 100 characters for best results

Result Management

• Use appropriate max_results value
• Process results incrementally for large queries
• Implement request timeouts
• Handle potential duplicate URLs

Limitations

Search Engine Constraints

• No guaranteed result ordering
• Search results may change over time
• No advanced search filters

Result Constraints

• HTML parsing may break if DuckDuckGo changes its format
• No image or video search results
• Limited to text-based results
• May not access personalized results