Request Options

Google Search Light provides several parameters to control what is returned. Use query or url. Other fields are optional.

query

Search query to submit.

• Type: string
• Max length: 1000
• Required unless url is provided

{
  "query": "coffee grinder"
}

url

A complete Google results URL to fetch exactly as given, instead of query.

• Type: string | null
• Max length: 2048
• Only https://www.google.com/search?q=... full results pages (no tbm, no udm)
• Not combined with query, locale, page, safe, time_range, or uule
• device, format, and ai_overview still apply

{
  "url": "https://www.google.com/search?q=coffee+grinder&hl=en&gl=us&start=10"
}

locale

Locale for the search.

• Language code: en
• Language-region: en-US
• Or all

{
  "query": "coffee grinder",
  "locale": "en-US"
}

page

Single result page to fetch.

• Type: integer
• Min: 1, Max: 20, Default: 1
• Each successfully returned page is billed as one unit

{
  "query": "coffee grinder",
  "page": 2
}

pages

Fetch pages 1 through N in one request (same session and exit IP).

• Type: integer
• Min: 1, Max: 10, Default: 1
• Always starts at page 1
• Not combined with url
• Not with page. A request with both returns 422
• Stops at the first failed or missing page; see pages_stopped
• Billed per page returned

{
  "query": "coffee grinder",
  "pages": 3
}

safe

Safe-search level.

• Values: off | moderate | strict
• Default: off

{
  "query": "coffee grinder",
  "safe": "moderate"
}

time_range

Restrict results to a recency window.

• Values: day | week | month | year

{
  "query": "coffee grinder",
  "time_range": "week"
}

device

Whose results page to fetch.

• Values: desktop | mobile | iphone | ipad
• Default: desktop
• Later pages follow page 1's device

{
  "query": "coffee grinder",
  "device": "mobile"
}

uule

Encoded Google location only (w+ place encoding or a+ coordinates).

• Max length: 512
• Plain location names are not resolved
• Invalid values return 422
• Later pages follow page 1's place

{
  "query": "coffee grinder",
  "uule": "w+CAIQICIaQXVzdGluLFRleGFzLFVuaXRlZCBTdGF0ZXM"
}

format

What each page carries.

• Values: json | html | both
• Default: json
• Response envelope is always JSON
• With Accept-Encoding: gzip, html and both may be gzip-compressed

{
  "query": "coffee grinder",
  "format": "both"
}

ai_overview

Also return Google's AI Overview when available.

• Type: boolean
• Default: false
• Page 1 only
• Missing overview does not fail the search
• When Google loads the overview after the page, we fetch it too, which can add a few seconds

{
  "query": "coffee grinder",
  "ai_overview": true,
  "format": "json"
}