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.