# csecraft
The `csecraft` Python library allows you to easily interact with the <b>Google Custom Search API</b>. This library provides methods for executing search queries, retrieving search results, paginating through search results, and accessing search metadata. Additionally, the library includes utility methods for displaying and analyzing search results, making it an ideal tool for applications that require embedded search functionality.
## Features
- **Search the web**: Perform Google Custom Search queries.
- **Paginate**: Navigate through multiple pages of search results.
- **Retrieve Results & Metadata**: Access detailed search information, metadata, and page maps.
- **Get Snippets**: Retrieve plain and HTML snippets for each result.
- **Spelling Suggestions**: Receive corrected search queries when available.
## Installation
To install this library, follow either of the following methods:
```bash
pip install csecraft
```
Or
```bash
git clone https://github.com/benkimz/csecraft.git
cd csecraft
pip install .
```
## Prerequisites
To use this library, you'll need:
- A Google Cloud Platform (GCP) project with the **Custom Search API** enabled.
- A Custom Search Engine ID (CX) and an API Key.
Visit the [Google Custom Search documentation](https://developers.google.com/custom-search) for setup instructions.
## Usage
### Importing and Initializing the CustomSearchEngine
```python
from cse-api import CustomSearchEngine
# Initialize the search engine with your API key and engine ID
api_key = "YOUR_API_KEY"
engine_id = "YOUR_ENGINE_ID"
search_engine = CustomSearchEngine(api_key, engine_id)
```
### Performing a Search
```python
query = "Python programming"
response = search_engine.search(query)
if response:
print("Search Results:")
search_engine.display_results()
else:
print("No results found.")
```
### Accessing Search Metadata
```python
# Get total number of results
total_results = search_engine.get_total_results()
print(f"Total results: {total_results}")
# Get search time
search_time = search_engine.get_search_time()
print(f"Search time: {search_time} seconds")
```
### Retrieving Results Information
```python
# Get all items (results) from the search
items = search_engine.get_items()
for i, item in enumerate(items, start=1):
print(f"{i}. Title: {item['title']}")
print(f" URL: {item['link']}")
print(f" Snippet: {item['snippet']}")
print(f" Display Link: {item['displayLink']}\n")
# Get promotions (if any)
promotions = search_engine.get_promotions()
for promo in promotions:
print(f"Promotion: {promo['title']}, Link: {promo['link']}")
```
### Fetching Corrected Query and Suggested Next Page
```python
# Get spelling-corrected query, if available
corrected_query = search_engine.get_corrected_query()
if corrected_query:
print(f"Did you mean: {corrected_query}?")
# Fetch search terms for the next page, if available
next_page_query = search_engine.get_next_page_query()
if next_page_query:
print(f"Suggested terms for next page: {next_page_query}")
```
### Pagination: Fetching Specific Pages
```python
# Fetch results for a specific page
page_number = 2
page_response = search_engine.fetch_page(page_number)
if page_response:
print(f"Results for page {page_number}:")
search_engine.display_results()
```
### Getting Plain and HTML Snippets
```python
# Retrieve plain and HTML snippets for each result
snippets = search_engine.get_snippets()
for snippet, html_snippet in snippets:
print("Plain Snippet:", snippet)
print("HTML Snippet:", html_snippet)
print()
```
## API Reference
### `CustomSearchEngine`
#### `__init__(api_key: str, engine_id: str, base_url: str = "https://customsearch.googleapis.com/customsearch/v1")`
Initialize the CustomSearchEngine with API key, engine ID, and an optional base URL.
#### `search(query: str, **kwargs) -> Optional[CustomSearchResponse]`
Perform a search with the given query and optional parameters.
- **query** (`str`): The search term or phrase.
- **kwargs**: Additional parameters, such as `num`, `start`, `language`, etc.
- **Returns**: A `CustomSearchResponse` object with the search results.
#### `get_total_results() -> int`
Returns the total number of results found in the last search response.
#### `get_search_time() -> float`
Returns the time taken for the last query in seconds.
#### `get_items() -> List[Dict[str, Any]]`
Retrieves a list of dictionaries with title, link, snippet, and display link for each search result.
#### `get_promotions() -> List[Dict[str, Any]]`
Retrieves a list of promotions from the last response, if available.
#### `get_corrected_query() -> Optional[str]`
Returns a spelling-corrected query if the API provides a suggestion.
#### `get_next_page_query() -> Optional[str]`
Retrieves the search terms for the next page of results if available.
#### `get_metadata() -> Dict[str, Any]`
Returns metadata from the last search context.
#### `get_pagemap_data() -> List[Dict[str, Any]]`
Retrieves page map data (metadata, images, etc.) from search results.
#### `fetch_page(page_number: int) -> Optional[CustomSearchResponse]`
Fetches a specific page of results based on the page number.
- **page_number** (`int`): The page number to fetch.
- **Returns**: A `CustomSearchResponse` for the specified page or `None` if an error occurs.
#### `display_results()`
Prints a formatted display of the search results for easy viewing in the console.
#### `last_search_info`
Property returning a dictionary with a summary of the last search results, including total results, search time, and formatted total results.
#### `get_snippets() -> List[Tuple[str, str]]`
Returns a list of tuples containing plain and HTML snippets for each result.
## Example Workflow
```python
# Initialize the engine
search_engine = CustomSearchEngine(api_key="YOUR_API_KEY", engine_id="YOUR_ENGINE_ID")
# Perform a search
search_engine.search("machine learning")
search_engine.display_results()
# Access total results and search time
print(f"Total Results: {search_engine.get_total_results()}")
print(f"Search Time: {search_engine.get_search_time()}")
# Fetch snippets
snippets = search_engine.get_snippets()
for plain_snippet, html_snippet in snippets:
print(f"Plain Snippet: {plain_snippet}")
print(f"HTML Snippet: {html_snippet}")
```
## License
This library is provided under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/benkimz/csecraft",
"name": "csecraft",
"maintainer": "@benkimz",
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "google, cse, api, search, custom search",
"author": "Benard K. Wachira (@benkimz)",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2b/27/9f4060cf1fdd090ab7975093ec7b1786de41ebe14d04eb10953bba63713d/csecraft-0.1.2.tar.gz",
"platform": "any",
"description": "# csecraft\r\n\r\nThe `csecraft` Python library allows you to easily interact with the <b>Google Custom Search API</b>. This library provides methods for executing search queries, retrieving search results, paginating through search results, and accessing search metadata. Additionally, the library includes utility methods for displaying and analyzing search results, making it an ideal tool for applications that require embedded search functionality.\r\n\r\n## Features\r\n\r\n- **Search the web**: Perform Google Custom Search queries.\r\n- **Paginate**: Navigate through multiple pages of search results.\r\n- **Retrieve Results & Metadata**: Access detailed search information, metadata, and page maps.\r\n- **Get Snippets**: Retrieve plain and HTML snippets for each result.\r\n- **Spelling Suggestions**: Receive corrected search queries when available.\r\n\r\n## Installation\r\n\r\nTo install this library, follow either of the following methods:\r\n\r\n```bash\r\npip install csecraft\r\n```\r\n\r\nOr\r\n\r\n```bash\r\ngit clone https://github.com/benkimz/csecraft.git\r\ncd csecraft\r\npip install .\r\n```\r\n\r\n## Prerequisites\r\n\r\nTo use this library, you'll need:\r\n\r\n- A Google Cloud Platform (GCP) project with the **Custom Search API** enabled.\r\n- A Custom Search Engine ID (CX) and an API Key.\r\n\r\nVisit the [Google Custom Search documentation](https://developers.google.com/custom-search) for setup instructions.\r\n\r\n## Usage\r\n\r\n### Importing and Initializing the CustomSearchEngine\r\n\r\n```python\r\nfrom cse-api import CustomSearchEngine\r\n\r\n# Initialize the search engine with your API key and engine ID\r\napi_key = \"YOUR_API_KEY\"\r\nengine_id = \"YOUR_ENGINE_ID\"\r\nsearch_engine = CustomSearchEngine(api_key, engine_id)\r\n```\r\n\r\n### Performing a Search\r\n\r\n```python\r\nquery = \"Python programming\"\r\nresponse = search_engine.search(query)\r\n\r\nif response:\r\n print(\"Search Results:\")\r\n search_engine.display_results()\r\nelse:\r\n print(\"No results found.\")\r\n```\r\n\r\n### Accessing Search Metadata\r\n\r\n```python\r\n# Get total number of results\r\ntotal_results = search_engine.get_total_results()\r\nprint(f\"Total results: {total_results}\")\r\n\r\n# Get search time\r\nsearch_time = search_engine.get_search_time()\r\nprint(f\"Search time: {search_time} seconds\")\r\n```\r\n\r\n### Retrieving Results Information\r\n\r\n```python\r\n# Get all items (results) from the search\r\nitems = search_engine.get_items()\r\nfor i, item in enumerate(items, start=1):\r\n print(f\"{i}. Title: {item['title']}\")\r\n print(f\" URL: {item['link']}\")\r\n print(f\" Snippet: {item['snippet']}\")\r\n print(f\" Display Link: {item['displayLink']}\\n\")\r\n\r\n# Get promotions (if any)\r\npromotions = search_engine.get_promotions()\r\nfor promo in promotions:\r\n print(f\"Promotion: {promo['title']}, Link: {promo['link']}\")\r\n```\r\n\r\n### Fetching Corrected Query and Suggested Next Page\r\n\r\n```python\r\n# Get spelling-corrected query, if available\r\ncorrected_query = search_engine.get_corrected_query()\r\nif corrected_query:\r\n print(f\"Did you mean: {corrected_query}?\")\r\n\r\n# Fetch search terms for the next page, if available\r\nnext_page_query = search_engine.get_next_page_query()\r\nif next_page_query:\r\n print(f\"Suggested terms for next page: {next_page_query}\")\r\n```\r\n\r\n### Pagination: Fetching Specific Pages\r\n\r\n```python\r\n# Fetch results for a specific page\r\npage_number = 2\r\npage_response = search_engine.fetch_page(page_number)\r\nif page_response:\r\n print(f\"Results for page {page_number}:\")\r\n search_engine.display_results()\r\n```\r\n\r\n### Getting Plain and HTML Snippets\r\n\r\n```python\r\n# Retrieve plain and HTML snippets for each result\r\nsnippets = search_engine.get_snippets()\r\nfor snippet, html_snippet in snippets:\r\n print(\"Plain Snippet:\", snippet)\r\n print(\"HTML Snippet:\", html_snippet)\r\n print()\r\n```\r\n\r\n## API Reference\r\n\r\n### `CustomSearchEngine`\r\n\r\n#### `__init__(api_key: str, engine_id: str, base_url: str = \"https://customsearch.googleapis.com/customsearch/v1\")`\r\n\r\nInitialize the CustomSearchEngine with API key, engine ID, and an optional base URL.\r\n\r\n#### `search(query: str, **kwargs) -> Optional[CustomSearchResponse]`\r\n\r\nPerform a search with the given query and optional parameters.\r\n\r\n- **query** (`str`): The search term or phrase.\r\n- **kwargs**: Additional parameters, such as `num`, `start`, `language`, etc.\r\n- **Returns**: A `CustomSearchResponse` object with the search results.\r\n\r\n#### `get_total_results() -> int`\r\n\r\nReturns the total number of results found in the last search response.\r\n\r\n#### `get_search_time() -> float`\r\n\r\nReturns the time taken for the last query in seconds.\r\n\r\n#### `get_items() -> List[Dict[str, Any]]`\r\n\r\nRetrieves a list of dictionaries with title, link, snippet, and display link for each search result.\r\n\r\n#### `get_promotions() -> List[Dict[str, Any]]`\r\n\r\nRetrieves a list of promotions from the last response, if available.\r\n\r\n#### `get_corrected_query() -> Optional[str]`\r\n\r\nReturns a spelling-corrected query if the API provides a suggestion.\r\n\r\n#### `get_next_page_query() -> Optional[str]`\r\n\r\nRetrieves the search terms for the next page of results if available.\r\n\r\n#### `get_metadata() -> Dict[str, Any]`\r\n\r\nReturns metadata from the last search context.\r\n\r\n#### `get_pagemap_data() -> List[Dict[str, Any]]`\r\n\r\nRetrieves page map data (metadata, images, etc.) from search results.\r\n\r\n#### `fetch_page(page_number: int) -> Optional[CustomSearchResponse]`\r\n\r\nFetches a specific page of results based on the page number.\r\n\r\n- **page_number** (`int`): The page number to fetch.\r\n- **Returns**: A `CustomSearchResponse` for the specified page or `None` if an error occurs.\r\n\r\n#### `display_results()`\r\n\r\nPrints a formatted display of the search results for easy viewing in the console.\r\n\r\n#### `last_search_info`\r\n\r\nProperty returning a dictionary with a summary of the last search results, including total results, search time, and formatted total results.\r\n\r\n#### `get_snippets() -> List[Tuple[str, str]]`\r\n\r\nReturns a list of tuples containing plain and HTML snippets for each result.\r\n\r\n## Example Workflow\r\n\r\n```python\r\n# Initialize the engine\r\nsearch_engine = CustomSearchEngine(api_key=\"YOUR_API_KEY\", engine_id=\"YOUR_ENGINE_ID\")\r\n\r\n# Perform a search\r\nsearch_engine.search(\"machine learning\")\r\nsearch_engine.display_results()\r\n\r\n# Access total results and search time\r\nprint(f\"Total Results: {search_engine.get_total_results()}\")\r\nprint(f\"Search Time: {search_engine.get_search_time()}\")\r\n\r\n# Fetch snippets\r\nsnippets = search_engine.get_snippets()\r\nfor plain_snippet, html_snippet in snippets:\r\n print(f\"Plain Snippet: {plain_snippet}\")\r\n print(f\"HTML Snippet: {html_snippet}\")\r\n```\r\n\r\n## License\r\n\r\nThis library is provided under the MIT License.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for easily interacting with the Google Custom Search API",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/benkimz/csecraft"
},
"split_keywords": [
"google",
" cse",
" api",
" search",
" custom search"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ab95752b34ff2a77846db64a6847ccf0d63645d8517ce620c96132be839e8817",
"md5": "2afd789e2133b61f4f9a5ddaec7bf6f7",
"sha256": "8926c97213dbb5b0e356719e79e5a9aab8774746bbbc69f73f75f88db1706a9d"
},
"downloads": -1,
"filename": "csecraft-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2afd789e2133b61f4f9a5ddaec7bf6f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7930,
"upload_time": "2024-11-02T14:31:20",
"upload_time_iso_8601": "2024-11-02T14:31:20.504183Z",
"url": "https://files.pythonhosted.org/packages/ab/95/752b34ff2a77846db64a6847ccf0d63645d8517ce620c96132be839e8817/csecraft-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2b279f4060cf1fdd090ab7975093ec7b1786de41ebe14d04eb10953bba63713d",
"md5": "7d0828aafd9736c730c3bbe992f1f291",
"sha256": "ddced776eb2bfda01c899a4cfdb3dbde7d7cbb7e676e6b929732f36a98f3cd04"
},
"downloads": -1,
"filename": "csecraft-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "7d0828aafd9736c730c3bbe992f1f291",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8696,
"upload_time": "2024-11-02T14:31:22",
"upload_time_iso_8601": "2024-11-02T14:31:22.110786Z",
"url": "https://files.pythonhosted.org/packages/2b/27/9f4060cf1fdd090ab7975093ec7b1786de41ebe14d04eb10953bba63713d/csecraft-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-02 14:31:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "benkimz",
"github_project": "csecraft",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "csecraft"
}
JSON
