Skip to main content
POST
Monitor Google Search Results
Extract structured data from Google Search results: organic results, sponsored ads, People Also Ask questions, related searches, and optional AI Overview data. When Google shows a right-rail product panel for the query, its merchant offers are returned as product results.
AI Overview supports a different set of countries than Google Search. Check with the countries endpoint using model=aioverview, not model=google.

​
Request parameters

Required parameters: Describe the search in one of two ways — either the standard fields, or a Google search URL:
  • query (string) and country (string): The search query to execute on Google (1-10,000 characters), plus the ISO 3166-1 alpha-2 country code (uppercase) for localized results. There is no default country
  • url (string): A complete Google search URL to run instead. See searching by URL
Optional parameters:
  • location (string): Google canonical location name for geo-targeted results (e.g., New York,New York,United States). See Google’s geo target list for all ~100,000 supported locations. Mutually exclusive with uule. When both location and uule are omitted, cloro defaults location to the requested country’s canonical name (e.g. Portugal for country: "PT") so results pin to the country instead of the proxy’s exit IP. Pass location or uule explicitly when you need city- or region-level precision
  • uule (string): Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with location
  • device (string): Device the search is run from. Options: desktop (default), ios, android, and mobile (an alias for android). ios emulates Safari on iPhone and android emulates Chrome on Android; all three phone values return the mobile SERP layout.
  • pages (integer): Number of search results pages to scrape (1-10). 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)
  • include.paaAioverview (boolean): Hydrate AI-Overview-type People Also Ask items with markdown content and cited sources. Defaults to false
Additional credit costEnabling include.aioverview or include.paaAioverview adds +2 credits. The add-on is inclusive: enabling both still adds +2 credits total, not +4.Each page beyond the first adds +2 credits (e.g. pages: 3 adds +4, pages: 10 adds +18). Read the exact charge for a request from the X-Credits-Charged response header. See providers for full pricing details.

​
Searching by URL

If you already assemble your own Google search URLs, send one as url instead of query and the targeting fields:
That is the whole body. country is derived from the URL’s gl. Pass country explicitly to override it, or when your URL has no gl. url is mutually exclusive with query, location, uule, and pages — the URL owns those values, and sending both is a 400. device and the include.* flags stay top level and behave exactly as they do in the standard shape. The response schema is identical, and so is the cost: a URL request is charged as the equivalent standard request, so num=30 resolves to 3 pages and is billed as pages: 3.

​
What cloro reads from the URL

cloro supports a fixed set of query parameters: Parameters outside this set — glp, lr and the like — don’t cause a rejection, but they’re dropped rather than applied to the search.

​
Starting from a given rank

start sets the rank your first page begins at, and results are labelled with the SERP page and position they actually came from. A URL with start=20 returns Google’s third page, with position counting from 21 and page reported as 3:
With no num, that returns a single page — the usual shape if you drive pagination yourself by issuing one request per start value. Add num to fetch several pages from the offset in one request: start=20 with num=30 returns ranks 21-30, 31-40 and 41-50.

​
Rejected URLs

A URL is rejected with a 400 when it:
  • Is not an absolute http/https URL
  • Is not on a Google web search host — google.com, google.co.uk, www.google.de and similar are accepted; subdomains such as news.google.com are not
  • Has a path other than /search
  • Has no q, or an empty one
  • Carries tbm, which targets a Google vertical with its own endpoint and pricing. For tbm=nws, use Google News instead
  • Has a gl cloro doesn’t support, with no explicit country to fall back on
  • Has neither gl nor an explicit country — cloro won’t guess a target

​
Requesting AI Overview

markdown (boolean, defaults to false) returns the AI Overview formatted as Markdown. Without the aioverview object, no AI Overview data is returned.

​
Error handling

AI Overview behaviorWhen Google returns no AI Overview for a query (after several retries), you get aioverview: null in a 200 response, with all other search data intact. In a region where AI Overview isn’t supported, include.aioverview fails with an UnsupportedInputError instead — a region-level error, not a query failure.

​
Response objects

result.html is also returned when include.html is true. It is an array of URLs — one per scraped page, so a pages: 3 request returns three entries — not a single URL string. Each URL expires after 24 hours.
result.knowledgeGraph, result.shoppingCards, result.productResults, result.peopleAreSaying, and result.localResults are omitted from result when the corresponding panel does not appear on the SERP. Treat them as optional rather than expecting null or an empty array.

​
Usage examples

​
Scrape multiple pages

Organic results, People Also Ask questions, and related searches from all 3 pages are combined into a single response. Each peopleAlsoAsk entry carries a page field marking which page it appeared on.

​
City and state-level geo-targeting

location accepts any Google canonical location name, including states and regions — not just cities.
For state-level targeting:

​
UULE geo-targeting

When you generate your own UULE values, pass uule instead of location — the two are mutually exclusive:

​
Hydrate People Also Ask with AI Overview content

AI-Overview-type People Also Ask items come back with markdown content and cited sources:
Combine it with AI Overview extraction:

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 unless you supply 'url' instead — the two are mutually exclusive.

Required string length: 1 - 10000
Example:

"best laptops for programming"

​
country
string
required

ISO 3166-1 alpha-2 country code for localized search results. Required in the standard request shape. When you supply 'url' instead, country is derived from the URL's 'gl' — pass it explicitly to override that, or when the URL has no 'gl'.

Example:

"US"

​
url
string<uri>

A complete Google web search URL to run instead of building the request from 'query' and the targeting fields. Must be an absolute http(s) URL on a Google web search host (google.com, google.co.uk, www.google.de, ...), with the path '/search' and a non-empty 'q'. Mutually exclusive with 'query', 'location', 'uule' and 'pages' — the URL owns those values. cloro applies a fixed set of query parameters — 'q', 'gl', 'hl', 'uule', 'num' (read as result depth), 'start', 'tbs' and 'safe' — and drops anything else. URLs carrying 'tbm' are rejected, because they target a Google vertical with its own endpoint and pricing (use POST /v1/monitor/google/news for tbm=nws).

Example:

"https://www.google.com/search?q=best+laptops+for+programming&hl=en&gl=us&num=30"

​
location
string

Google canonical location name for geo-targeted results, in comma-separated format: 'City,Region,Country' (see https://developers.google.com/google-ads/api/reference/data/geotargets for all ~100,000 supported locations). Use alongside 'country' for city-level precision. Mutually exclusive with 'uule' — provide one or the other, not both. Cannot be combined with 'url'.

Example:

"New York,New York,United States"

​
uule
string

Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with 'location' — provide one or the other, not both. Cannot be combined with 'url'; put 'uule' in the URL's query string instead.

Example:

"w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5"

​
device
enum<string>
default:desktop

Device the search is run from. 'desktop' returns the desktop SERP; 'ios' (Safari on iPhone), 'android' (Chrome on Android) and 'mobile' (alias for 'android') all return the mobile SERP.

Available options:
desktop,
mobile,
ios,
android
Example:

"desktop"

​
pages
integer
default:1

Number of search results pages to scrape (1-10). Cannot be combined with 'url' — in that shape, depth comes from the URL's 'num' (rounded up to whole pages of 10, capped at 10 pages).

Required range: 1 <= x <= 10
Example:

3

​
include
object

Optional flags for including additional response data

Response

successful Google monitoring response

​
success
boolean
required
Example:

true

​
result
object
required

Google search results data