Extract Google AI Overview

Overview

The Google Search endpoint extracts structured data from Google Search results, including organic results, People Also Ask questions, related searches, and optional AI Overview data. This endpoint replaces the dedicated AI Overview endpoint.

AI Overview location availability might be different than regular Google Search availability. Use the countries endpoint with model=aioverview to check supported countries, as the available locations differ significantly from Google Search (model=google) availability.

Request parameters

Required parameters:

query (string): The search query to execute on Google (1-10,000 characters)

Optional parameters:

country (string): ISO 3166-1 alpha-2 country code for localized results. Defaults to US
city (string): Canonical city name for hyperlocal search results. Use canonical city names from the Google Ads geotargets.
device (string): Device type for search results. Options: desktop (default), mobile.
pages (integer): Number of search results pages to scrape (1-20). Defaults to 1
include.html (boolean): Include raw HTML response. Defaults to false
include.aioverview (object): Include Google AI Overview. Set markdown: true for markdown formatting. Defaults to false (not included)

Error handling

AI Overview behaviorWhen include.aioverview is requested and Google doesn’t return an AI Overview (after several retries), the API returns aioverview: null in a 200 response.The response will include all other Google search data (organic results, People Also Ask, etc.) with aioverview set to null:

{
  "success": true,
  "result": {
    "organicResults": [...],
    "peopleAlsoAsk": [...],
    "relatedSearches": [...],
    "aioverview": null
  }
}

AI Overview request structure

To request AI Overview data, nest the aioverview object under the include parameter:

{
  "query": "best laptops for programming",
  "include": {
    "aioverview": {
      "markdown": true
    }
  }
}

AI Overview options:

markdown (boolean): Include AI Overview formatted as Markdown. Defaults to false
When aioverview is not included in the request, no AI Overview data will be returned

Response schema

Includes common response fields plus:

Google Search results

Field	Type	Description
`result.organicResults`	array	Organic search results from Google
`result.peopleAlsoAsk`	array	”People Also Ask” questions with answers
`result.relatedSearches`	array	Related search suggestions
`result.html`	string	Raw HTML response (if requested)

Organic results

Field	Type	Description
`position`	number	Position in search results (1-indexed)
`title`	string	Title of the search result
`link`	string	URL of the search result
`displayedLink`	string	Formatted URL as displayed in search results
`snippet`	string	Search result snippet
`page`	number	Page number where result was found (for multi-page)

Field	Type	Description
`question`	string	The question being asked
`type`	string	Type of result (AIOVERVIEW or LINK)
`snippet`	string	Answer snippet for LINK type questions
`title`	string	Title for LINK type questions
`link`	string	URL for LINK type questions

Field	Type	Description
`query`	string	Related search query
`link`	string	Google search URL for the related query

AI Overview results

Field	Type	Description
`result.aioverview`	object	Google AI Overview data (if requested)
`result.aioverview.text`	string	AI Overview text content
`result.aioverview.sources`	array	Sources referenced in AI Overview
`result.aioverview.sources.position`	number	Position of source in AI Overview
`result.aioverview.sources.label`	string	Title of the source
`result.aioverview.sources.url`	string	URL of the source
`result.aioverview.sources.description`	string	Description of the source
`result.aioverview.markdown`	string	AI Overview in markdown format (if requested)

Usage examples

Hyperlocal search with city parameter

{
  "query": "restaurants near me",
  "city": "New York"
}

{
  "query": "best coffee shops",
  "city": "Paris,Île-de-France"
}

{
  "query": "hotels near me",
  "city": "Tokyo,Tokyo,Japan"
}

Use the city parameter to get hyperlocal search results for specific locations. The backend automatically converts canonical city names to Google’s location parameter. City name formats supported:

City only: “New York”, “Paris”, “Tokyo”
City with region: “Paris,Île-de-France”, “New York,New York”
City with region and country: “Tokyo,Tokyo,Japan”, “London,England,United Kingdom”

Use canonical city names from the Google Ads geotargets.

Scrape multiple pages

{
  "query": "best laptops for programming",
  "pages": 3,
  "country": "US"
}

This will scrape the first 3 pages of Google search results, combining all organic results, People Also Ask questions, and related searches into a single response. The peopleAlsoAsk results include a page field indicating which page each question appeared on.

Retrieve AI Overview

To get AI Overview data with markdown formatting:

{
  "query": "best laptops for programming",
  "include": {
    "aioverview": {
      "markdown": true
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request parameters for monitoring Google search results

query

string

required

The search query to execute on Google

Required string length: 1 - 10000

Example:

"best laptops for programming"

country

string

ISO 3166-1 alpha-2 country code for localized search results

Example:

"US"

city

string

Canonical city name for hyperlocal search results. Use canonical city names from the Google Ads geotargets

Example:

"New York"

device

enum<string>

default:desktop

Device type for search results

Available options:

desktop,

mobile

Example:

"desktop"

pages

integer

default:1

Number of search results pages to scrape (1-20)

Required range: 1 <= x <= 20

Example:

3

include

object

Optional flags for including additional response data

Show child attributes

include.html

boolean

default:false

Include raw HTML response from Google search

Example:

false

include.aioverview

object

Include Google AI Overview in the response

Show child attributes

include.aioverview.markdown

boolean

default:false

Include AI Overview formatted as markdown

Example:

true

Response

successful Google monitoring response

success

boolean

required

Example:

true

result

object

required

Google search results data

Show child attributes

result.organicResults

object[]

Organic search results from Google

Show child attributes

result.organicResults.position

number

Position in search results (1-indexed)

Example:

1

result.organicResults.title

string

Title of the search result

Example:

"Best Laptops for Programming in 2024"

result.organicResults.link

string

URL of the search result

Example:

"https://example.com/best-programming-laptops"

result.organicResults.displayedLink

string

Formatted URL as displayed in search results

Example:

"https://example.com"

result.organicResults.snippet

string

Text snippet describing the page content

Example:

"Looking for the best programming laptops? We've tested and reviewed the top options..."

result.organicResults.date

string

Publication date if available

Example:

"2 days ago"

result.organicResults.sitelinks

object

Sitelinks displayed under the main result

Show child attributes

result.organicResults.sitelinks.inline

object[]

Inline sitelinks

Show child attributes

result.organicResults.sitelinks.inline.title

string

Example:

"Specifications"

result.organicResults.sitelinks.inline.link

string

Example:

"https://example.com/specs"

result.peopleAlsoAsk

object[]

People Also Ask questions from Google

Show child attributes

result.peopleAlsoAsk.question

string

The question text

Example:

"What specs should I look for in a programming laptop?"

result.peopleAlsoAsk.type

enum<string>

Type of question result

Available options:

AIOVERVIEW,

LINK,

UNKNOWN

result.peopleAlsoAsk.snippet

string

Answer snippet (for LINK type)

Example:

"Key specifications include RAM, processor, storage, and display quality..."

result.peopleAlsoAsk.title

string

Result title (for LINK type)

Example:

"Essential laptop specs for developers"

result.peopleAlsoAsk.link

string

Result URL (for LINK type)

Example:

"https://example.com/laptop-specs"

Related search suggestions

Show child attributes

Related search query

Example:

"best budget laptop for coding"

Google search URL for the related query

Example:

"https://google.com/search?q=best+budget+laptop+for+coding"

result.aioverview

object

Google AI Overview data (if requested). Returns null when AI Overview is not available after retries.

Show child attributes

result.aioverview.sources

object[]

Sources referenced in the AI Overview

Show child attributes

result.aioverview.sources.position

number

Position index of the source

Example:

1

result.aioverview.sources.title

string

Source title

Example:

"Best Programming Laptops 2024"

result.aioverview.sources.link

string

Source URL

Example:

"https://example.com/programming-laptops"

result.aioverview.sources.snippet

string

Source description

Example:

"Comprehensive guide to choosing the perfect laptop for software development"

result.aioverview.text

string

AI Overview text content

Example:

"Based on current information, the best laptops for programming typically include models from Apple MacBook Pro, Dell XPS, and Lenovo ThinkPad series..."

result.aioverview.markdown

string

AI Overview content formatted as markdown (if requested)

Example:

"Based on current information, the best laptops for programming typically include models from Apple MacBook Pro, Dell XPS, and Lenovo ThinkPad series..."

result.html

string<uri>[]

Raw HTML from Google search page (if requested)

Example:

[
  "https://storage.cloro.dev/results/b83e8dfd-c3a1-4b98-83b9-af91adc21e26/page-1.html"
]

​Overview

​Request parameters

​Error handling

​AI Overview request structure

​Response schema

​Google Search results

​Organic results

​People Also Ask

​Related searches

​AI Overview results

​Usage examples

​Hyperlocal search with city parameter

​Scrape multiple pages

​Retrieve AI Overview

Authorizations

Body

Response

Overview

Request parameters

Error handling

AI Overview request structure

Response schema

Google Search results

Organic results

People Also Ask

Related searches

AI Overview results

Usage examples

Hyperlocal search with city parameter

Scrape multiple pages

Retrieve AI Overview