Basic Search Implementation

To begin using Eternity for web data retrieval, you need a valid Google Custom Search API Key and a Search Engine ID (CX). This section demonstrates how to initialize the library and retrieve search results.

Initializing the Client

First, import the Eternity class and initialize it with your credentials.

from eternity.eternity import Eternity

# Replace with your actual credentials
API_KEY = "your_google_api_key"
ENGINE_ID = "your_custom_search_engine_id"

eternity = Eternity(api_key=API_KEY, engine_id=ENGINE_ID)

Performing a Query

The search() method is the primary way to retrieve raw data from the web. It returns a list of dictionaries, where each dictionary represents a search result.

Usage Example

query = "Python web scraping best practices"
results = eternity.search(query)

# Iterate through the results
for result in results:
    title = result.get("title")
    link = result.get("link")
    snippet = result.get("snippet")
    
    print(f"Title: {title}")
    print(f"URL: {link}")
    print(f"Description: {snippet}\n")

Search Output Details

The search() method returns a list of items containing the following key fields:

Retrieving Formatted Text

If you need a quick summary of the top results for logging or processing (such as feeding data into an LLM), use the get_combined_text() method. This method automatically aggregates the top 5 results into a single, human-readable string.

Usage Example

query = "Recent breakthroughs in quantum computing"
summary = eternity.get_combined_text(query)

print(summary)

What it returns: get_combined_text() returns a string formatted as follows for the first 5 results:

Result 1:
Title: [Title]
Snippet: [Description]
URL: [Link]

Result 2:
...

Error Handling

If a search fails (e.g., due to invalid credentials or network issues), the search() method will print an error message to the console and return an empty list []. Always ensure your API limits have not been exceeded when performing high volumes of queries.