GoogleSearch 1.0.0

Overview

Function Intermediate

Description

Performs web searches using the Google Custom Search API and returns structured, paginated results. This block integrates with Google's Custom Search Engine to provide programmatic access to search functionality with configurable pagination support.

Key Features: - Structured search results using Pydantic models - Configurable pagination (10 results per page) - Rich metadata including search performance metrics - HTML and plain text result snippets - Support for custom search engines

Configuration Options

Name	Data Type	Description	Default Value
google_api_key	str	Google API key with access to the Custom Search API. Obtain this from the Google Cloud Console with Custom Search API enabled.	N/A
search_engine_id	str	Custom Search Engine ID (cx parameter). Create and configure your custom search engine at https://cse.google.com/	N/A
page	int	Page number for pagination (1-based). Each page returns up to 10 results. Page 1 shows results 1-10, page 2 shows results 11-20, etc.	1

Inputs

Name	Data Type	Description
query	str	The query string to search on Google

Outputs

Name	Data Type	Description
search_results	GoogleSearchResponse	Structured search response containing results, metadata, and pagination info. Includes search items with titles, URLs, snippets, and additional structured data when available.

Examples

Basic Usage Advanced

# Basic web search
- id: search_python_tutorials
  uses: GoogleSearch@1.0.0
  with:
    google_api_key: "AIzaSyBOG_YOUR_API_KEY_HERE"
    search_engine_id: "017576662512468239146:omuauf_lfve"
    query: "Python programming tutorials for beginners"
  outputs:
    search_results: python_results

# Search with specific page number
- id: search_page_2
  uses: GoogleSearch@1.0.0
  with:
    google_api_key: "AIzaSyBOG_YOUR_API_KEY_HERE"
    search_engine_id: "017576662512468239146:omuauf_lfve"
    page: 2
    query: "machine learning frameworks comparison"
  outputs:
    search_results: ml_results_page2

# Multi-page search workflow
- id: search_first_page
  uses: GoogleSearch@1.0.0
  with:
    google_api_key: "AIzaSyBOG_YOUR_API_KEY_HERE"
    search_engine_id: "017576662512468239146:omuauf_lfve"
    page: 1
    query: "artificial intelligence latest research papers"
  outputs:
    search_results: ai_results_p1

- id: search_second_page
  uses: GoogleSearch@1.0.0
  with:
    google_api_key: "AIzaSyBOG_YOUR_API_KEY_HERE"
    search_engine_id: "017576662512468239146:omuauf_lfve"
    page: 2
    query: "artificial intelligence latest research papers"
  outputs:
    search_results: ai_results_p2

# Extract specific fields from search results
- id: extract_titles_and_links
  uses: GetJsonField@1.0.0
  with:
    json_field_structure: "$.items[*].{title: title, link: link, snippet: snippet}"
    json_object: "Reference to search results from previous step"
  outputs:
    field: extracted_results

# Domain-specific search with custom search engine
- id: search_company_docs
  uses: GoogleSearch@1.0.0
  with:
    google_api_key: "AIzaSyBOG_YOUR_API_KEY_HERE"
    search_engine_id: "custom_engine_for_company_site"
    query: "API documentation authentication"
  outputs:
    search_results: internal_docs

# Conditional pagination based on results
- id: search_with_pagination
  uses: GoogleSearch@1.0.0
  with:
    google_api_key: "AIzaSyBOG_YOUR_API_KEY_HERE"
    search_engine_id: "017576662512468239146:omuauf_lfve"
    page: 1
    query: "cloud computing best practices"
  outputs:
    search_results: cloud_results

- id: check_more_results
  uses: GetJsonField@1.0.0
  with:
    json_field_structure: "$.queries.nextPage"
    json_object: "Reference to cloud_results"
  outputs:
    field: has_next_page

Error Handling

GoogleAPIAuthenticationError

Error Code

google_api_auth_failed

Common Cause

Invalid or expired Google API key, or API key lacks Custom Search API permissions

Solution

Verify API key is correct, ensure Custom Search API is enabled in Google Cloud Console, check API quotas and billing settings

CustomSearchEngineError

Error Code

custom_search_engine_invalid

Common Cause

Invalid search engine ID (cx parameter) or search engine is not properly configured

Solution

Verify search engine ID at https://cse.google.com/, ensure search engine is active and properly configured with search sites

SearchQuotaExceededError

Error Code

search_quota_exceeded

Common Cause

Daily search quota limit reached (free tier: 100 searches/day, paid: up to 10,000)

Solution

Wait until quota resets, upgrade to paid plan, or optimize search frequency to stay within limits

SearchResultsParsingError

Error Code

search_results_parsing_failed

Common Cause

Unexpected API response format or network connectivity issues

Solution

Check internet connectivity, verify API response format, retry the search, report persistent issues

FAQ

How do I get a Google API key and search engine ID?

1. Go to Google Cloud Console and create/select a project. 2. Enable the Custom Search API. 3. Create API credentials (API key). 4. Visit https://cse.google.com/ to create a Custom Search Engine and get the search engine ID (cx parameter).

What's included in the GoogleSearchResponse object?

The response includes search items (title, link, snippet), search metadata (total results, search time), pagination info (nextPage queries), and structured data (pagemap) when available. Each item contains both HTML and plain text versions of titles and snippets.

How does pagination work with the page parameter?

Each page returns up to 10 results. Page 1 shows results 1-10, page 2 shows 11-20, etc. The block automatically calculates the start index: (page - 1) * 10 + 1. Check queries.nextPage in the response to see if more pages are available.

Can I search specific websites or domains only?

Yes, configure your Custom Search Engine at https://cse.google.com/ to include specific sites or use site: operators in your query ("site:example.com your search terms"). You can create multiple search engines for different site collections.

What are the API usage limits and costs?

Free tier: 100 searches per day. Paid tier: up to 10,000 searches per day at $5 per 1,000 queries. Monitor usage in Google Cloud Console. Consider caching results and optimizing search frequency to manage costs effectively.