# ScrapingBee Google Search API

> Retrieve detailed Google SERP data, including classic results, news, maps, shopping, images, Lens, AI mode, and ads.

## Endpoint and authentication

- Endpoint: `https://app.scrapingbee.com/api/v1/google`
- Required input: `search`.
- Authentication: `Authorization: Bearer YOUR_API_KEY`.
- The `api_key` query parameter remains supported for backward compatibility but is deprecated for new integrations.
- URL-encode special characters in `search`. Google operators such as `site:`, `inurl:`, and `intitle:` are supported.

## Parameters

| Parameter | Default / valid use |
| --- | --- |
| `light_request` | `true` by default; set `false` for a regular browser request and AI Overviews. |
| `search_type` | `classic` (default), `news`, `maps`, `lens`, `shopping`, `images`, `ai_mode`, or `ads`. |
| `country_code`, `language` | Defaults are `us` and `en`. |
| `device` | `desktop` (default) or `mobile`; `news` is unavailable on mobile. |
| `page`, `pages` | Both default to `1`; `pages` is at most `10`; three or fewer is recommended. |
| `nfpr` | `false` by default; `true` disables Google auto-correction. |
| `date_range` | Empty by default; `past_hour`, `past_day`, `past_week`, `past_month`, or `past_year`; only classic, news, and images. |
| `latitude`, `longitude`, `radius` | Geographic point in decimal degrees and radius in meters. Latitude and longitude must be supplied together; radius takes effect only with both. |
| `extra_params` | URL-encoded Google URL parameters. Encode `&` as `%26` when sending multiple values. |
| `add_html` | `false` by default; set `true` to include `full_html`. The documented example wraps this under `body`, while the standard response example is flat; handle either shape. |
| Shopping filters | `sort_by`: `relevance`, `reviews`, `price_asc`, `price_desc`; `min_price`, `max_price`. |
| `tag` | Returned in response headers only; it does not change scraping behavior. |

## Constraints and response

- `search_type=lens` requires an image URL in `search`.
- `search_type=ai_mode` accepts at most 400 input characters.
- `search_type=ads` uses the classic-result structure but is optimized for paid-ad visibility.
- AI Overviews are a response field, not `search_type=ai_mode`; they require `light_request=false` and are non-deterministic. When present, they contain `answer_text` fragments and optional source references, `bullet_list` points, and `source_panel.items`.
- `sort_by`, `min_price`, and `max_price` apply only to `search_type=shopping`. Price thresholds use the native marketplace currency selected by `country_code` (for example, `de` uses EUR and `us` uses USD).
- `date_range` applies only to classic, news, and images search types.
- `page=2&pages=3` fetches Google pages 2–4 and combines the results in one response. Use no more than three pages at once for reliability even though ten is allowed. The source does not explicitly state multi-page billing semantics, so verify them before a billing-sensitive workload.
- Light requests do not use a browser: they are faster and cheaper but can omit data that a regular request returns. Use `light_request=false` when result completeness or AI Overviews matters.
- ScrapingBee retries failed Google searches for up to 30 seconds. Account for that server-side retry window in the client timeout and retry policy.
- Typical response fields include `organic_results`, `top_ads`, `bottom_ads`, `knowledge_graph`, `local_results`, `map_results`, `images`, `top_stories`, `news_results`, `hotel_results`, `questions`, `related_queries`, `related_searches`, `ai_overviews`, and `meta_data`.
- Cost per successful request: 10 credits for the default light request; 15 credits with `light_request=false`. `Spb-cost` reports the request cost in response headers.