# Google Related Searches Scraper (`googleapi/google-related-searches-scraper`) Actor

Collect Google related-search suggestions and optionally nest visible results from each linked Google Search page.

- **URL**: https://apify.com/googleapi/google-related-searches-scraper.md
- **Developed by:** [Google API](https://apify.com/googleapi) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

Collect related search phrases from public Google Search pages. Each dataset record contains a suggested phrase and its Google Search URL. By default, the Actor stops there. You can optionally open a bounded number of those Google Search pages and attach the visible result cards to each suggestion.

Third-party result links are saved as links; the Actor does not open those destination pages.

### How to use

1. Enter a search phrase, several phrases, or Google Search URLs.
2. Choose the result pages and the total suggestion limit.
3. Leave `includeSearchResults` off to collect related phrases only, or enable it to add Google result cards.
4. Run the Actor and inspect the dataset.

Example: related phrases only

```json
{
  "queries": ["web scraping", "structured data"],
  "language": "en",
  "country": "US",
  "maxItems": 25,
  "page": 1,
  "maxPages": 1
}
```

Example: add cards from linked Google searches

```json
{
  "query": "coffee shops in Chennai",
  "country": "IN",
  "includeSearchResults": true,
  "maxSearchPages": 2,
  "maxSearchResults": 5,
  "maxLocalPlaces": 3,
  "maxItems": 10
}
```

### Input

| Input | Description | Default |
|---|---|---:|
| `query` / `queries` | One or more Google Search phrases. `keywords` and `searchQuery` are aliases. | — |
| `startUrls` | Public Google Search URLs with a `q` query. `urls` is an alias. | — |
| `language` / `country` | Language and country for Google Search. Country can be two-letter code or `ALL`. | `en` / `US` |
| `page` / `maxPages` | Starting results page and consecutive pages per query. | 1 / 1 |
| `maxItems` | Maximum unique suggestion records across all searches. | 25 |
| `includeSearchResults` | Fetch linked Google Search pages and attach visible cards to their suggestion. | `false` |
| `maxSearchPages` | Global limit on linked Google Search pages when enrichment is enabled. | 10 |
| `maxSearchResults` | Maximum web, discussion, shopping, and ad cards attached per page. | 10 |
| `maxLocalPlaces` | Maximum local-business cards from the same page. Set to `0` to omit local cards. | 5 |
| `sourceTransport` | Start with direct HTTP (`http`) or a standard browser (`browser`). | `http` |
| `renderJavaScript` | Allow a standard browser render if the page requires JavaScript. | `true` |
| `proxyConfiguration` | Optional Apify Proxy settings. | — |

### Output

Each dataset item represents one related-search suggestion and requires `suggestion` and `suggestionUrl`. When linked search results are enabled and available, it may also contain:

- **Search cards:** web results, discussions, shopping offers, and ads, with displayed title, snippet, type, date, price, and publisher details when visible.
- **Discussion context:** visible community name, comment/answer counts, top-answer excerpt, and related discussion links.
- **Local places:** business name, rating, review-count label, price range, category, address, services, and image URL when present.

Suggestions stay as parent records even if an optional linked search has no supported cards or cannot be fetched. Result card links are not visited. Search-result dates and price labels are preserved as displayed rather than estimated or normalized.

Example dataset item:

```json
{
  "suggestion": "Web scraping python",
  "suggestionUrl": "https://www.google.com/search?q=Web+scraping+python&hl=en&gl=US",
  "searchResults": [
    {
      "title": "A Practical Introduction to Web Scraping in Python",
      "resultUrl": "https://realpython.com/python-web-scraping-practical-introduction/",
      "resultType": "web",
      "snippet": "Python web scraping allows you to collect and parse data.",
      "site": {
        "siteName": "Real Python",
        "domainName": "realpython.com"
      }
    }
  ],
  "localPlaces": [
    {
      "name": "Example Coffee House",
      "ratingValue": 4.7,
      "ratingScale": 5,
      "businessCategory": "Coffee shop"
    }
  ]
}
```

The Output tab shows the available result fields. Run summary information is available with the run output in Apify.

### Limits and responsible use

Search phrases, locale, and result types affect what Google displays. Extra linked-page collection increases run time. The Actor stops when Google limits access and does not bypass access checks.

Search terms are submitted to Google. Use public search data responsibly and follow applicable privacy requirements and Google Search terms. This Actor is not affiliated with Google.

# Actor input Schema

## `sourceTransport` (type: `string`):

Use direct HTTP with the existing JavaScript-shell fallback, or a fresh standard browser session from the start. Both stop at access boundaries. Browser sessions use more compute and do not reuse account cookies.

## `query` (type: `string`):

One search phrase to submit to public Google Search.

## `queries` (type: `array`):

Multiple search phrases. Each query is processed as a separate Google Search page.

## `keywords` (type: `array`):

Compatibility alias for the queries array.

## `searchQuery` (type: `string`):

Compatibility alias for one search phrase.

## `startUrls` (type: `array`):

Public Google Search /search URLs with a q search parameter.

## `urls` (type: `array`):

Compatibility alias for public Google Search URLs.

## `language` (type: `string`):

Google Search interface language code used for generated search URLs.

## `country` (type: `string`):

Two-letter Google Search country code, or ALL to omit the country parameter.

## `page` (type: `integer`):

One-based Google Search page to start from; Google uses ten-result offsets.

## `maxPages` (type: `integer`):

Maximum number of Google Search pages to inspect for each query.

## `maxItems` (type: `integer`):

Global maximum of unique suggestions across all queries and pages.

## `includeSearchResults` (type: `boolean`):

Opt in to fetch linked public Google Search pages and nest supported visible web, discussion, shopping, ad and local-business cards. Result destination pages are never fetched.

## `maxSearchPages` (type: `integer`):

Global cap on additional Google Search pages fetched for unique suggestions when enrichment is enabled. Each unique suggestion URL uses at most one page.

## `maxSearchResults` (type: `integer`):

Maximum web, discussion, shopping, and ad result cards to include from each linked Google Search page when enrichment is enabled.

## `maxLocalPlaces` (type: `integer`):

Maximum Google local-business cards to include from each already-fetched linked Search page. Set to 0 to omit local business cards; this does not create additional page requests.

## `timeoutSecs` (type: `integer`):

Maximum time for each public Google Search request.

## `requestDelayMs` (type: `integer`):

Polite delay between public Google Search requests.

## `maxRetries` (type: `integer`):

Bounded retries for transient public request failures.

## `maxResponseBytes` (type: `integer`):

Maximum size of each public Google Search response.

## `renderJavaScript` (type: `boolean`):

Use one standard Playwright render when direct public HTML is only a JavaScript-required shell. HTTP 401/403/429 responses and CAPTCHA or other access boundaries stop without browser fallback or retries.

## `browserWaitMs` (type: `integer`):

Bounded wait after the public search page loads.

## `browserScrolls` (type: `integer`):

Bounded ordinary scrolling to reveal visible related-search content.

## `proxyConfiguration` (type: `object`):

Optional existing Apify Proxy configuration applied to every source and linked Google Search HTTP request and to an ordinary JavaScript-shell browser render. Initialization/authentication failures stop without direct fallback.

## Actor input object example

```json
{
  "sourceTransport": "http",
  "language": "en",
  "country": "US",
  "page": 1,
  "maxPages": 1,
  "maxItems": 25,
  "includeSearchResults": false,
  "maxSearchPages": 10,
  "maxSearchResults": 10,
  "maxLocalPlaces": 5,
  "timeoutSecs": 30,
  "requestDelayMs": 200,
  "maxRetries": 1,
  "maxResponseBytes": 3000000,
  "renderJavaScript": true,
  "browserWaitMs": 2500,
  "browserScrolls": 1
}
```

# Actor output Schema

## `dataset` (type: `string`):

Suggestion parent records, with bounded nested searchResults only when explicitly enabled.

## `output` (type: `string`):

No description

## `runHealth` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxItems": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("googleapi/google-related-searches-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "maxItems": 25 }

# Run the Actor and wait for it to finish
run = client.actor("googleapi/google-related-searches-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxItems": 25
}' |
apify call googleapi/google-related-searches-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,googleapi/google-related-searches-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/4mGyh0BBhSHw0iZcn/builds/bPjGdZpigXqtxoPEI/openapi.json