Overview
This node performs Google Custom Search operations, specifically enabling users to execute custom search queries using a specified Google Custom Search Engine ID. It is useful for automating web searches within workflows, extracting search results programmatically, and integrating Google search capabilities into automation pipelines.
Common scenarios include:
- Retrieving search results for specific queries in bulk.
- Filtering search results by country, date, file type, or site.
- Performing image-specific searches with various filters like color, size, and type.
- Automating data collection from Google search results for analysis or reporting.
For example, a user can input a query like "latest technology trends" and receive structured search results limited to a particular country or domain, or perform an image search filtered by dominant color and size.
Properties
| Name | Meaning |
|---|---|
| Search Engine ID | The custom search engine ID to use for this request. |
| Query | The search query string to use for this request. |
| Return All Results | Whether to return all available results or only up to a specified limit. |
| Limit | Maximum number of search results to return (used if "Return All Results" is false). Range: 1 to 100. |
| Additional Fields | A collection of optional parameters to refine the search results: |
| - Country Restriction (cr) | Restricts search results to documents originating in a particular country. |
| - Date Restrict | Restricts results to URLs based on date (e.g., d[number], w[number], m[number], y[number]). |
| - Exact Terms | Phrase that all documents in the search results must contain. |
| - Exclude Terms | Word or phrase that should not appear in any documents in the search results. |
| - File Type | Restricts results to files of a specified extension (e.g., pdf, ppt, svg). |
| - GL Parameter | Geolocation of end user (two-letter country code). |
| - Google Domain | The Google domain to use (e.g., google.com, google.de). Defaults to "www.google.com". |
| - High Range | Specifies the ending value for a search range. |
| - HL Parameter | Sets the user interface language. |
| - Image Color Type | Returns black and white, grayscale, transparent, or color images. Options: Color, Gray Scale, Monochrome, Transparent. |
| - Image Dominant Color | Returns images of a specific dominant color. Options include Black, Blue, Brown, Gray, Green, Pink, Purple, Teal, White, Yellow. |
| - Image Size | Returns images of a specified size. Options: Extra Large, Icon, Large, Medium, Small, Extra Large (2MP), Extra Extra Large (4MP). |
| - Image Type | Returns images of a type. Options: Clip Art, Face, Line Drawing, News, Photo, Animated. |
| - Link Site | Specifies that all search results should contain a link to a particular URL. |
| - Low Range | Specifies the starting value for a search range. |
| - Number | Number of search results to return per request (max 10). |
| - Rights | Filters based on licensing (e.g., cc_publicdomain, cc_attribute, cc_sharealike). |
| - Safe | Search safety level. Options: Active, Off. Default is Off. |
| - Search Type | Specifies the search type. Currently supports "image". |
| - Site Search | Specifies a given site which should be included or excluded in the search results. |
| - Site Search Filter | Controls whether to include or exclude results from the site named in the Site Search parameter. Options: Include, Exclude. |
| - Sort | The sort expression to apply to the results. |
| - Start | The index of the first result to return. Range: 1 to 91. |
Output
The node outputs a JSON array where each item corresponds to a search result returned by the Google Custom Search API. Each item contains detailed information about a single search result, such as title, snippet, link, and other metadata provided by the API.
If the search type is set to "image," the results will include image-specific metadata.
No binary data output is produced by this node.
Dependencies
- Requires an API key credential with OAuth tokens for authenticating requests to the Google Custom Search API.
- Uses the official Google Custom Search REST API endpoint:
https://www.googleapis.com/customsearch/v1. - Requires proper configuration of the Google Custom Search Engine and associated credentials in n8n.
Troubleshooting
- Authentication errors: Ensure the API key credential is valid and has the necessary permissions. Refresh OAuth tokens if expired.
- Quota limits: Google Custom Search API enforces usage quotas; exceeding these will cause errors. Monitor quota usage in your Google Cloud Console.
- Invalid Search Engine ID: Verify that the provided Search Engine ID is correct and active.
- Empty results: If no items are returned, check query syntax and additional fields filters; overly restrictive filters may yield no results.
- Parameter validation: Some parameters have strict formats (e.g., dateRestrict, safe). Invalid values may cause API errors.
- Pagination issues: When "Return All Results" is enabled, the node paginates through results up to a maximum start index of 91 due to API constraints.