---
title: "Google web search"
method: GET
path: "/v1/google/search"
tags: ["Google Search"]
---

# Google web search

`GET /v1/google/search`

Search Google and get structured results.

Two response modes:

- **full** (default, 2 credits): complete SERP with organic, ads,
  knowledge graph, People Also Ask, AI Overview, local pack, news,
  related searches, inline videos, etc. ~1.5-2s cold, ~1.5ms warm.
- **fast** (1 credit, ~40% faster): lite endpoint (`gbv=1`) returning
  only organic results + related searches. Rich blocks (KG, local,
  AI Overview, news) are **not** returned — request ``mode=full`` for
  those. Auto-upgrades to full if ``ai_overview=true`` is set.

First request in either mode triggers a browser warmup (~15s) to
solve SearchGuard. Subsequent requests reuse the sticky session.

## Query parameters

- `q` string, required — Search query (supports Google operators like site:, inurl:, intitle:)
- `gl` string — Country code (e.g. us, gb, de, fr)
- `hl` string — Language code (e.g. en, es, fr)
- `num` integer — Results per page
- `start` integer — Pagination offset (0, 10, 20...)
- `domain` string — Google domain (e.g. google.com, google.co.uk)
- `device` string — desktop or mobile
- `location` string, nullable — City-level geo-targeting (e.g. 'New York, USA')
- `lr` string, nullable — Language restrict (e.g. lang_en)
- `tbs` string, nullable — Time-based search filter (e.g. qdr:d for past 24h)
- `safe` string — Safe search (active/off)
- `uule` string, nullable — Encoded location parameter (UULE)
- `filter` integer, nullable — Include omitted results (0=show all, 1=filter)
- `nfpr` integer — Disable auto-correction (1=exact match)
- `cr` string, nullable — Country restrict (e.g. countryUS|countryGB)
- `ludocid` string, nullable — Google My Business CID (place ID)
- `lsig` string, nullable — Knowledge Graph map view ID
- `kgmid` string, nullable — Knowledge Graph entity ID
- `si` string, nullable — Cached search parameters
- `ibp` string, nullable — Layout control (e.g. gwp;0,7)
- `uds` string, nullable — Google filter string
- `ai_overview` boolean — When true, chase Google's deferred AI Overview page_token with a follow-up fetch and merge the result into ai_overview. Adds ~1s and 1 credit when the SERP actually defers the overview.
- `mode` 'full' | 'fast' — Response mode. **full** (default): complete SERP with all blocks (organic, ads, knowledge graph, local pack, AI overview, news, related questions, etc). **fast**: lite endpoint via `gbv=1` that returns ONLY organic results + related searches in ~0.6-1s cold (vs 1.5-2s full). Use when you only need organic results and can skip rich features.

## Response `200`

Successful Response

- GoogleSearchResponse — Response for GET /api/v1/search.
  - `search_information` SearchInformation, required — Metadata about the search query.
    - `query_displayed` string, required
    - `total_results` integer, nullable
    - `time_taken` number, nullable
    - `organic_results_state` string, nullable
    - `url` string, nullable
  - `ai_overview` AiOverview — Google AI Overview (AI-generated summary). Google increasingly serves the AI Overview as a **deferred** block — the initial SERP HTML contains only a placeholder plus a `page_token` that the client has to POST back to retrieve the actual content. When that happens, the SERP parser populates `page_token` and leaves `text_blocks`/`references` empty. Callers of `/v1/google/search` can pass `ai_overview=true` to have the scraper chase the token automatically and merge the result back into this object.
    - `text_blocks` AiOverviewTextBlock[]
      - `type` 'paragraph' | 'heading' | 'list' | 'video' | 'table', required
      - `snippet` string, nullable
      - `snippet_links` SnippetLink[]
        - `link` string, required
        - `link_text` string, required
      - `list_items` AiOverviewListItem[]
        - `title` string, nullable
        - `snippet` string, nullable
        - `snippet_links` SnippetLink[]
          - `link` string, required
          - `link_text` string, required
      - `video` AiOverviewVideo — Video reference in AI Overview.
        - `link` string, required
        - `channel` string, nullable
        - `source` string, nullable
        - `date` string, nullable
        - `thumbnail` string, nullable
        - `duration` string, nullable
      - `video_links` AiOverviewVideo[]
        - `link` string, required
        - `channel` string, nullable
        - `source` string, nullable
        - `date` string, nullable
        - `thumbnail` string, nullable
        - `duration` string, nullable
    - `references` AiOverviewReference[]
      - `index` integer, required
      - `title` string, required
      - `link` string, required
      - `snippet` string, nullable
      - `source` string, nullable
      - `logo` string, nullable
    - `page_token` string, nullable — Continuation token for the deferred AI Overview fetch. Non-null when Google embeds only a placeholder in the main SERP response.
    - `deferred` boolean — True when the AI Overview was present as a deferred block.
  - `organic_results` OrganicResult[]
    - `position` integer, required
    - `title` string, required
    - `link` string, required
    - `displayed_link` string, nullable
    - `snippet` string, nullable
    - `highlighted_keywords` string[]
    - `source` string, nullable
    - `favicon` string, nullable
    - `sitelinks` Sitelink[]
      - `title` string, required
      - `link` string, nullable
      - `snippet` string, nullable
    - `inline_sitelinks` InlineSitelink[]
      - `title` string, nullable
      - `date` string, nullable
    - `date` string, nullable
    - `rank` integer, nullable
    - `page_rank` integer, nullable
  - `ads` AdResult[]
    - `position` integer, nullable
    - `title` string, required
    - `link` string, required
    - `displayed_link` string, nullable
    - `description` string, nullable
    - `extensions` string[]
  - `knowledge_graph` KnowledgeGraph — Knowledge Graph panel.
    - `title` string, nullable
    - `type` string, nullable
    - `description` string, nullable
    - `image` string, nullable
    - `source` string, nullable
    - `attributes` object
  - `local_results` LocalResult[]
    - `title` string, required
    - `place_id` string, nullable
    - `rating` number, nullable
    - `reviews` integer, nullable
    - `address` string, nullable
    - `phone` string, nullable
    - `type` string, nullable
    - `gps_coordinates` GpsCoordinates — GPS coordinates.
      - `lat` number, required
      - `lng` number, required
  - `related_questions` RelatedQuestion[]
    - `question` string, required
    - `rank` integer, nullable
    - `title` string, nullable
    - `link` string, nullable
    - `snippet` string, nullable
    - `displayed_link` string, nullable
    - `source_logo` string, nullable
  - `related_searches` RelatedSearch[]
    - `query` string, required
    - `link` string, nullable
  - `news_results` NewsResult[]
    - `title` string, required
    - `link` string, nullable
    - `source` string, nullable
    - `date` string, nullable
    - `thumbnail` string, nullable
  - `inline_videos` InlineVideo[]
    - `title` string, required
    - `source` string, nullable
    - `thumbnail` string, nullable
    - `platform` string, nullable
    - `duration` string, nullable
    - `date` string, nullable
    - `position` integer, nullable
  - `shopping_results` ShoppingResult[]
    - `title` string, required
    - `price` string, nullable
    - `source` string, nullable
    - `link` string, nullable
    - `thumbnail` string, nullable
    - `rating` number, nullable
    - `reviews` integer, nullable
  - `pagination` Pagination, required — Pagination metadata.
    - `current` union
      - integer
      - string
    - `next` string, nullable
    - `total_results` integer, nullable
    - `total_pages` integer, nullable
    - `page_no` object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/scrapebadger/apis/scrapebadger-account-api.md) · [All operations](https://skmtc.net/scrapebadger/apis/scrapebadger-account-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scrapebadger/scrapebadger-account-api/revisions/4a1ef8777baf/schema)