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, and see AI Overview for what a request returns when Google shows none.

Request parameters

Describe the search in one of two ways:
  • query (string) and country or gl: The search query (1-10,000 characters), plus the ISO 3166-1 alpha-2 country code for localized results. There is no default country
  • url (string): A complete Google search URL to run instead. See searching by URL
Every other field is optional and listed in the request body schema below.
Additional credit costinclude.aioverview and include.paaAioverview share one flat +2 credits, and each page after the first adds +2 (pricing). X-Credits-Charged on the response reports the exact charge.

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, and the interface language from the URL’s hl. Pass country, gl, or hl explicitly to fill in when the URL has no copy of that parameter. The URL owns query, location, uule, pages, country/gl, and hl. Sending an explicit value alongside a URL that already carries a different one is a 400 that names the field you sent — for example, gl: "DE" next to ?gl=us returns Cannot set both url and gl; the URL owns this value. Values that agree with the URL’s copy still pass, and the check is case-insensitive on the country code (gl: "us" and ?gl=US are the same value). 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 labeled 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

Response schema

Every section except AI Overview is returned without an include flag; result.aioverview requires include.aioverview.
result.knowledgeGraph, result.shoppingCards, result.productResults, result.peopleAreSaying, result.recipes, result.localResults, result.sportsResults, result.relatedWebsites, result.inlineImages, result.videos, result.shortVideos, result.weather, result.latestPosts, result.financeQuote, result.events, result.discussionsAndForums, result.thingsToKnow, result.transitResults, result.flights, result.hotelResults, result.stores, result.comparisonShoppingSites, and result.topSights 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:

Authorizations

Authorization
string
header
required

cloro API key as a bearer token. One key grants every endpoint in this spec; per-key scopes are not available, so a client cannot request a narrower permission. Keys are created and revoked in the dashboard.

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
enum<string>
required

ISO 3166-1 alpha-2 country code for localized search results. See List of countries for the codes each provider supports. Required in the standard request shape unless you send gl. 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'.

Available options:
AD,
AE,
AF,
AG,
AI,
AL,
AM,
AO,
AQ,
AR,
AS,
AT,
AU,
AW,
AX,
AZ,
BA,
BB,
BD,
BE,
BF,
BG,
BH,
BI,
BJ,
BL,
BM,
BN,
BO,
BQ,
BR,
BS,
BT,
BV,
BW,
BY,
BZ,
CA,
CC,
CD,
CF,
CG,
CH,
CI,
CK,
CL,
CM,
CN,
CO,
CR,
CU,
CV,
CW,
CX,
CY,
CZ,
DE,
DJ,
DK,
DM,
DO,
DZ,
EC,
EE,
EG,
EH,
ER,
ES,
ET,
FI,
FJ,
FK,
FM,
FO,
FR,
GA,
GB,
GD,
GE,
GF,
GG,
GH,
GI,
GL,
GM,
GN,
GP,
GQ,
GR,
GS,
GT,
GU,
GW,
GY,
HK,
HM,
HN,
HR,
HT,
HU,
ID,
IE,
IL,
IM,
IN,
IO,
IQ,
IR,
IS,
IT,
JE,
JM,
JO,
JP,
KE,
KG,
KH,
KI,
KM,
KN,
KP,
KR,
KW,
KY,
KZ,
LA,
LB,
LC,
LI,
LK,
LR,
LS,
LT,
LU,
LV,
LY,
MA,
MC,
MD,
ME,
MF,
MG,
MH,
MK,
ML,
MM,
MN,
MO,
MP,
MQ,
MR,
MS,
MT,
MU,
MV,
MW,
MX,
MY,
MZ,
NA,
NC,
NE,
NF,
NG,
NI,
NL,
NO,
NP,
NR,
NU,
NZ,
OM,
PA,
PE,
PF,
PG,
PH,
PK,
PL,
PM,
PN,
PR,
PS,
PT,
PW,
PY,
QA,
RE,
RO,
RS,
RU,
RW,
SA,
SB,
SC,
SD,
SE,
SG,
SH,
SI,
SJ,
SK,
SL,
SM,
SN,
SO,
SR,
SS,
ST,
SV,
SX,
SY,
SZ,
TC,
TD,
TF,
TG,
TH,
TJ,
TK,
TL,
TM,
TN,
TO,
TR,
TT,
TV,
TW,
TZ,
UA,
UG,
UM,
US,
UY,
UZ,
VA,
VC,
VE,
VG,
VI,
VN,
VU,
WF,
WS,
XK,
YE,
YT,
ZA,
ZM,
ZW
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"

gl
string

Alternative to country, using Google's own parameter name for the result geography. Same ISO 3166-1 alpha-2 codes, accepted in either case (us or US), and must be a country the endpoint supports — see GET /v1/countries. Provide country or gl; sending both with different values is a 400.

Example:

"us"

hl
string

Interface language, as Google's own hl parameter (e.g. en, de, pt-BR). Free-form and case-insensitive — Google owns the list of codes. Overrides the language cloro derives from the country, so the interface language and the result geography can differ.

Example:

"en"

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'. When both location and uule are omitted, cloro pins results to the country's canonical location (e.g. Portugal for PT) where it has one; otherwise Google geolocates from the proxy's exit IP.

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). Paid add-on: +2 credits per page after the first (pricing). 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