# Google Search API

> Source: https://scrape.do/documentation/google-scraper-api/search/

Scrape Google search results as structured JSON data

![Google Search API](/uploads/google-serp-api.png)

The Google Search API is a specialized plugin that scrapes Google Search Engine Results Pages and returns fully parsed, structured JSON data. Instead of dealing with raw HTML and complex parsing logic, you get clean JSON with organic results, ads, knowledge graphs, local listings, and 10+ more result types ready to use in your applications.

> [!NOTE]
> **Credit Usage:** Each request costs **10 credits** for `/plugin/google/search` and `/plugin/google/search/ai-mode`. The AI Overview follow-up endpoint costs **5 credits**. For bulk processing, use the [Async API with plugins](/documentation/async-api/plugins/).

## Key Features

- **AI Overview & AI Mode**: Get Google's AI-generated overviews from SERP results, or use the dedicated AI Mode endpoint for full conversational AI responses with references and shopping results.
- **Structured JSON Output**: Get 15+ SERP result types parsed into clean JSON including organic results, ads, knowledge graphs, local packs, video results, and more. Organic rankings stay clean: ads, local packs, maps, and news cards are returned separately and do not consume `organic_results` positions.
- **84 Google Domains**: Target any regional Google domain from `google.com` to `google.co.jp`, `google.de`, `google.com.tr`, and more.
- **150+ Interface Languages**: Full support for every Google-supported `hl` language code, from major languages to regional dialects.
- **240+ Country Codes**: Target any country with `gl` for geo location and `cr` for strict country filtering — every ISO 3166-1 alpha-2 code supported.
- **35 Language Restrict Filters**: Apply strict language filtering with the `lr` parameter across all Google-supported language codes.
- **Advanced Localization**: Control host language (`hl`), geo location (`gl`), and precise location targeting with UULE encoding.
- **Device Emulation**: Get desktop or mobile SERP layouts with the `device` parameter.
- **Result Filtering**: Apply language and country restrictions, SafeSearch, time-based filters, and disable spell correction.
- **Stable Pagination Support**: Navigate through search result pages with the `start` offset parameter. Send `start=0` from the first request of a sweep to keep pages on one browsing session and reduce repeated or reshuffled results.
- **Include HTML Option**: Add `include_html=true` to any request to receive the full raw Google HTML alongside the parsed JSON data.
- **No Blocks or CAPTCHAs**: All anti-bot measures are handled automatically by Scrape.do.

---

## Endpoints

| Endpoint | Method | Output | Description | Details |
|----------|--------|--------|-------------|---------|
| `/plugin/google/search` | GET | JSON | Search Google and get structured SERP results | [more](/documentation/google-scraper-api/search/search) |
| `/plugin/google/search/ai-overview` | GET | JSON | Fetch a deferred AI Overview from a SERP response | [more](/documentation/google-scraper-api/search/search#fetching-a-deferred-ai-overview) |
| `/plugin/google/search/ai-mode` | GET | JSON | AI-generated answers with references from Google AI Mode | [more](/documentation/google-scraper-api/search/ai-mode) |

### Credit Costs

| Endpoint | Credits per Request |
|----------|---------------------|
| `/plugin/google/search` | 10 |
| `/plugin/google/search/ai-overview` | 5 |
| `/plugin/google/search/ai-mode` | 10 |

---

## Authentication

All requests require your Scrape.do API token passed via the `token` query parameter:

```
https://api.scrape.do/plugin/google/search?token=YOUR_TOKEN&q=your+search+query
```

---

## Response Format

Responses are returned as **JSON** (gzip compressed, minimum 2KB). Array fields always return `[]` when empty (never `null`). Object fields return `null` when absent. The `html` field is completely omitted unless `include_html=true` is set.

> [!NOTE]
> Parameter keys are **case-insensitive**. You can use `q`, `Q`, `hl`, `HL`, etc.

---

## Error Handling

All endpoints return errors in a consistent JSON format:

```json
{
  "error": "error_code",
  "message": "Human readable error message"
}
```

### Error Codes

| Status Code | Error | Description |
|-------------|-------|-------------|
| `400` | `token is required` | Missing authentication token |
| `400` | `q (search query) is required` | Missing search query |
| `400` | `device must be one of: desktop, mobile` | Invalid device value |
| `400` | `invalid google_domain` | Domain not in the supported list |
| `400` | `start must be a non-negative integer` | Invalid pagination offset |
| `502` | `request failed` | Upstream Google request failed, retry the request |
| `502` | `unexpected response` | Unparseable upstream response |
| `500` | `decompression failed` | Response decompression error |
| `500` | `failed to parse search results` | HTML parsing failure |
| `404` | `session not found` | AI Overview session key is invalid or expired |

---