Quick Start

Quick Start

Get up and running with Eternity in under five minutes. This guide covers installation, configuration, and performing your first real-time web search.

Installation

Install the library using pip:

pip install Eternity

1. Configuration

Eternity utilizes the Google Custom Search JSON API. Before you begin, you will need:

1. A Google API Key.
2. A Custom Search Engine ID (CX).

2. Basic Usage

The primary interface is the Eternity class. Initialize it with your credentials to start querying the web.

from eternity.eternity import Eternity

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

# Perform a raw search
results = client.search("latest news on SpaceX")

# Access the first result's title and link
if results:
    print(f"Top Result: {results[0].get('title')}")
    print(f"URL: {results[0].get('link')}")

3. Retrieve Formatted Results

If you need a human-readable summary or data ready for a Large Language Model (LLM) prompt, use the get_combined_text method. This returns a formatted string containing the top 5 search results.

from eternity.eternity import Eternity

client = Eternity(api_key="YOUR_API_KEY", engine_id="YOUR_ENGINE_ID")

# Get a formatted string of the top 5 results
summary = client.get_combined_text("Python web scraping best practices")

print(summary)

Output Example:

Result 1:
Title: Web Scraping with Python: A Complete Guide
Snippet: Learn how to extract data from websites using BeautifulSoup and Requests...
URL: https://example.com/guide

Result 2:
...

API Reference

Eternity(api_key: str, engine_id: str)

Initializes the search engine client.

• api_key: Your Google Cloud API Key.
• engine_id: Your Programmable Search Engine ID.

search(query: str) -> list[dict]

Performs a search and returns a list of raw result objects from the Google API.

• query: The search string.
• Returns: A list of dictionaries containing title, link, snippet, etc.

get_combined_text(query: str) -> str

A utility method that aggregates the top 5 results into a single formatted string.

• query: The search string.
• Returns: A multiline string containing titles, snippets, and URLs.