Search Operator (Serper)

Overview

The Search LOP acts as an interface to the Serper.dev Google Search API, enabling various search types directly within TouchDesigner. It can perform standard web searches, image searches, video searches, academic searches (Scholar), patent lookups, shopping results, map queries, business reviews, and even provide autocomplete suggestions. Results are fetched asynchronously and stored internally, with options to parse specific result types into dedicated output DATs.

API Key Required & Online Service

This operator requires a valid API key from Serper.dev. It relies on an external online service and requires an internet connection to function.

Requirements

• Serper API Key: Obtain an API key from Serper.dev and enter it into the Serper API Key parameter on the ‘API Key’ page.
• ChatTD Operator: Required for asynchronous task execution and logging. Ensure the ChatTD Operator parameter on the ‘About’ page points to your configured ChatTD instance.
• Standard Python Libraries: Uses the built-in requests library for API calls (no special external Python packages needed).

Input/Output

Inputs

None (Search queries and parameters are configured via the operator’s parameters).

Outputs

• Internal results_table DAT: Stores the raw JSON response for every search performed. Columns: query_id, query, type, result (JSON string), timestamp.
• Internal query_table DAT: Logs basic information about each query attempt. Columns: query_id, status, timestamp.
• Formatted Output DATs (selected via Output DAT parameter): These DATs parse specific sections of the raw JSON result from the results_table into structured tables:
  • search_results: Standard web search results (title, link, snippet, etc.).
  • search_related: Related search queries.
  • search_map_results: Results from a Map search.
  • search_shopping: Shopping results.
  • search_info: General information about the search query. (Note: The exact structure and availability of these tables depend on the Search Type used and the data returned by the Serper API for that query.)
• Viewer TOP (image_viewer): When the View parameter is set to image_view, displays the image corresponding to the result selected by the Select Result Index parameter (primarily useful for Image searches).

Parameters

Page: Serper

Search Type (Searchtype) op('search').par.Searchtype Menu

Default:

images

Options:

search, images, videos, scholar, patents, shopping, maps, reviews, autocomplete

Search Query (Query) op('search').par.Query Str

Default:

None

Execute Search (Search) op('search').par.Search Pulse

Default:

None

Clear Results (Clear) op('search').par.Clear Pulse

Default:

None

Current Status (Status) op('search').par.Status String

Default:

Ready

Output DAT (Outputdat) op('search').par.Outputdat Menu

Default:

search_results

Options:

search_results, search_related, search_map_results, search_shopping, search_info

View (View) op('search').par.View Menu

Default:

image_view

Options:

image_view, output_dat

Select Result Index (Selectresult) op('search').par.Selectresult Int

Default:

1

Range:

1 to N/A

Slider Range:

1 to N/A

Auto-select Last Result (Autosetselect) op('search').par.Autosetselect Toggle

Default:

On

Time Filter (Timefilter) op('search').par.Timefilter Menu

Default:

any

Options:

any, qdr:h, qdr:d, qdr:w, qdr:m, qdr:y

Location (Location) op('search').par.Location Str

Default:

None

Language Code (Language) op('search').par.Language Menu

Default:

en

Options:

en, es, fr, de, it, pt, nl, ru, ja, ko, zh, ar, hi, bn, pa, tr, vi, th, el, he, pl, uk, cs, sv, da, fi, no, hu, ro, id

Country Code (Country) op('search').par.Country Menu

Default:

us

Options:

us, gb, ca, au, nz, fr, de, it, es, pt, nl, be, ch, at, se, no, dk, fi, is, ie, jp, kr, cn, tw, hk, sg, my, th, vn, id, in, pk, bd, np, lk, ru, ua, pl, cz, hu, gr, tr, il, ae, sa, br, mx, ar, cl, co, za, ng, ke, eg, ma

GPS Coordinates (@lat,long,zoom) (Gpscoords) op('search').par.Gpscoords Str

Default:

None

Place ID (Placeid) op('search').par.Placeid Str

Default:

None

Customer ID (CID) (Cid) op('search').par.Cid Str

Default:

None

Sort Reviews By (Sortby) op('search').par.Sortby Menu

Default:

mostRelevant

Options:

mostRelevant, newest, highestRating, lowestRating

Number of Results (Numresults) op('search').par.Numresults Int

Default:

10

Range:

1 to N/A

Slider Range:

1 to 100

Page Number (Page) op('search').par.Page Int

Default:

1

Range:

1 to N/A

Slider Range:

1 to 10

Enable Autocorrect (Autocorrect) op('search').par.Autocorrect Toggle

Default:

On

Page: API Key

Serper API Key (Apikey) op('search').par.Apikey Str

Default:

API KEY LOADED

Get API Key (Getapikey) op('search').par.Getapikey Pulse

Default:

None

Page: About

Bypass (Bypass) op('search').par.Bypass Toggle

Default:

Off

Show Built-in Parameters (Showbuiltin) op('search').par.Showbuiltin Toggle

Default:

Off

Version (Version) op('search').par.Version String

Default:

1.0.0

Last Updated (Lastupdated) op('search').par.Lastupdated String

Default:

2024-11-10

Creator (Creator) op('search').par.Creator String

Default:

dotsimulate

Website (Website) op('search').par.Website String

Default:

https://dotsimulate.com

ChatTD Operator (Chattd) op('search').par.Chattd OP

Default:

/dot_lops/ChatTD

Usage Examples

Basic Image Search

1. Enter your Serper API Key on the 'API Key' page.
2. On the 'Serper' page, set 'Search Type' to 'Images'.
3. Enter your query in 'Search Query' (e.g., "abstract generative art").
4. Set 'Number of Results' (e.g., 20).
5. Pulse 'Execute Search'.
6. Set 'View' to 'image_view'.
7. Use 'Select Result Index' to browse the fetched images in the operator viewer.

Web Search for Recent News

1. Ensure API Key is set.
2. Set 'Search Type' to 'Web Search'.
3. Enter query (e.g., "latest AI developments").
4. Set 'Time Filter' to 'Past week'.
5. Set 'Country' and 'Language' as needed.
6. Pulse 'Execute Search'.
7. Set 'View' to 'output_dat'.
8. Set 'Output DAT' to 'search_results' to view standard results or 'search_related' for related queries.

Finding Local Businesses (Maps Search)

1. Ensure API Key is set.
2. Set 'Search Type' to 'Maps'.
3. Enter query (e.g., "coffee shops").
4. Enter a location in 'Location' (e.g., "San Francisco, CA") or precise 'GPS Coordinates'.
5. Pulse 'Execute Search'.
6. Set 'View' to 'output_dat'.
7. Set 'Output DAT' to 'search_map_results' to see the parsed map results.

Technical Notes

• API Key Storage: Your Serper API key is stored securely in a local configuration file (serper_config.json) within your system’s ChatTD application data folder.
• Asynchronous Operation: Search requests are made asynchronously using ChatTD’s TDAsyncIO, preventing the main TouchDesigner thread from freezing during the web request.
• Result Parsing: The operator parses common fields from the Serper JSON response into specific output DATs based on the Output DAT parameter. The raw JSON is always stored in the internal results_table for full access.
• Rate Limits: Be mindful of the request limits associated with your Serper API key plan.
• Parameter Visibility: Some parameters (like Time Filter, GPS Coordinates, Sort By) are only enabled when the relevant Search Type is selected.

Related Operators

• ChatTD: Provides core services like asynchronous task execution and logging required by this operator.