Web Search API Usage Guide

Empower your applications with Radient's Web Search API, providing instant access to vast amounts of information from the internet. Whether you're building research tools, AI agents that need real-time data, or enhancing content discovery, our Search API offers a streamlined way to fetch and utilize web search results.

This guide details how to perform searches, filter results, and leverage different search parameters.

Core Concepts

Radient's Web Search API is accessible via the /v1/search endpoint. It allows you to submit search queries and receive structured results from various underlying search providers.

Key features:

Flexible Queries: Perform broad or highly specific searches.
Parameter Control: Customize the number of results, request raw content, and filter by domain.
Provider Agnostic (Optional): Use Radient's default provider or specify one if needed.

Performing a Web Search

Submit a query and retrieve a list of relevant web pages.

Endpoint: GET /v1/search

Example Request (Python using requests):

import requests
import json

RADIENT_API_KEY = "YOUR_RADIENT_API_KEY"
RADIENT_BASE_URL = "https://api.radient.com/v1" # Or your specific Radient API endpoint

headers = {
    "Authorization": f"Bearer {RADIENT_API_KEY}",
    "Content-Type": "application/json" # Though GET, some APIs might check Content-Type for consistency
}

params = {
    "query": "latest breakthroughs in quantum computing",
    "max_results": 5,
    # "provider": "your_preferred_search_provider_id", # Optional
    # "include_raw": False, # Optional, defaults to False
    # "search_depth": "basic", # Optional, e.g., "basic" or "advanced"
    # "domains": "example.com,anotherdomain.org" # Optional, comma-separated
}

try:
    response = requests.get(f"{RADIENT_BASE_URL}/search", headers=headers, params=params)
    response.raise_for_status() # Raises an HTTPError for bad responses (4XX or 5XX)
    
    search_data = response.json()
    
    print(f"Search Query: {search_data.get('query')}")
    if search_data.get('provider'):
        print(f"Provider Used: {search_data.get('provider')}")

    if search_data.get("results"):
        print("\nSearch Results:")
        for i, result in enumerate(search_data["results"]):
            print(f"  Result {i+1}:")
            print(f"    Title: {result.get('title')}")
            print(f"    URL: {result.get('url')}")
            print(f"    Snippet: {result.get('content')}")
            if result.get('raw_content'):
                print(f"    Raw Content: {result.get('raw_content')[:200]}...") # Print a snippet of raw content
    elif search_data.get("error"):
         print(f"\nSearch Error: {search_data.get('error')}")
    else:
        print("\nNo results found or unexpected response format.")
        print("Full response:", search_data)

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
    print(f"Response body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request error occurred: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode JSON response.")
    print(f"Response body: {response.text}")

Request Query Parameters:

Parameter	Type	Description	Required	Default
`query`	string	The search query.	Yes
`max_results`	integer	Maximum number of search results to return.	No	10
`provider`	string	Specify a particular web search provider.	No
`include_raw`	boolean	Whether to include full raw content of search results (if available from the provider).	No	`false`
`search_depth`	string	Search depth (e.g., "basic", "advanced"). Provider-dependent.	No
`domains`	string	Comma-separated list of domains to restrict the search to.	No

Response Body (200 OK - WebSearchResponse):

Field	Type	Description
`query`	string	The original search query.
`results`	array of `RadientSearchResult`	List of search results. Each result object contains:
		- `title` (string): Title of the search result.
		- `url` (string): URL of the search result.
		- `content` (string): Snippet or summary of the content.
		- `raw_content` (string, optional): Full raw content if `include_raw` was true and available.
`provider`	string (optional)	The provider used for the search.
`error`	string (optional)	Error message if the search failed.

Other common responses include:

400 Bad Request: Invalid request payload.
401 Unauthorized: API key is missing or invalid.
500 Internal Server Error: An error occurred on the server.

Expected Response Structure (JSON):

{
  "query": "latest breakthroughs in quantum computing",
  "results": [
    {
      "title": "Quantum Computing Leaps Forward with New Qubit Design - Tech Journal",
      "url": "https://exampletechjournal.com/quantum_breakthrough_2024",
      "content": "Researchers have unveiled a novel qubit design that promises increased stability and coherence, paving the way for more powerful quantum computers...",
      "raw_content": null // or "<html>...</html>" if include_raw=true and available
    },
    {
      "title": "Understanding Quantum Entanglement | Physics Today",
      "url": "https://physicstoday.example.org/quantum_entanglement_explained",
      "content": "A deep dive into the principles of quantum entanglement and its implications for computing and communication..."
    }
    // ... more results
  ],
  "provider": "radient_default_search_provider", // Example
  "error": null // Or an error message string if the search failed
}

Advanced Search: Using `search_depth` and `include_raw`

For tasks requiring in-depth content analysis, such as RAG (Retrieval Augmented Generation) systems, you might want to use search_depth: "advanced" and include_raw: true. This combination attempts to fetch more comprehensive content from the result URLs.

params_advanced = {
    "query": "explain the concept of zero-knowledge proofs",
    "max_results": 3,
    "include_raw": True,
    "search_depth": "advanced" 
}

# ... (rest of the request code as above, using params_advanced) ...
# When processing results:
# if result.get('raw_content'):
#     # Process the full HTML or extracted text from raw_content
#     full_page_text = extract_text_from_html(result.get('raw_content')) # Requires an HTML parsing library
#     print(f"    Full Content Snippet: {full_page_text[:500]}...")

Note: Using include_raw: true and search_depth: "advanced" can lead to longer response times and larger data transfer due to fetching and processing full page contents.

Filtering by Domains

Focus your search on specific websites by using the domains parameter.

params_domain_specific = {
    "query": "Radient API documentation",
    "max_results": 5,
    "domains": "radient.com,docs.radient.com" # Search only within these domains
}

# ... (rest of the request code as above, using params_domain_specific) ...

Listing Available Search Providers

You can query the API to see which web search providers are available.

Endpoint: GET /v1/search/providers