The search() Method

The search() Method

The search() method is the primary interface for performing web searches. It queries the Google Custom Search API and returns a structured list of results based on the provided search terms.

Syntax

results = eternity_instance.search(query)

Parameters

| Parameter | Type | Description | | :--- | :--- | :--- | | query | str | The search string or keywords you want to look up on the web. |

Return Value

The method returns a list of dictionaries.

• Success: Each dictionary in the list represents a single search result "item" containing metadata provided by Google.
• Failure/No Results: If the API request fails (e.g., invalid credentials, rate limits) or no matches are found, the method returns an empty list [].

Result Data Structure

Each dictionary in the returned list follows the schema defined by the Google Custom Search API. Common keys include:

• title: The title of the webpage.
• link: The full URL of the result.
• snippet: A brief excerpt or description of the content.
• displayLink: The domain name of the result.
• pagemap: (Optional) Rich metadata such as thumbnails, dates, or author information.

Usage Example

from eternity import Eternity

# Initialize the client
et = Eternity(api_key="YOUR_GOOGLE_API_KEY", engine_id="YOUR_ENGINE_ID")

# Perform a search
results = et.search("OpenAI API documentation")

# Iterate through results
for item in results:
    print(f"Title: {item.get('title')}")
    print(f"Link: {item.get('link')}")
    print("-" * 20)

Error Handling

The search() method handles API communication internally. If the Google API returns a non-200 status code, the error status is printed to the console and an empty list is returned to prevent the application from crashing. Ensure your api_key and engine_id are valid to avoid empty responses.