Skip to main content
POST
/
v1
/
monitor
/
google
Monitor Google Search Results
curl --request POST \
  --url https://api.cloro.dev/v1/monitor/google \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "best laptops for programming",
  "country": "US",
  "location": "New York,New York,United States",
  "uule": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5",
  "device": "desktop",
  "pages": 3,
  "include": {
    "html": false
  }
}
'
{
  "success": true,
  "result": {
    "organicResults": [
      {
        "position": 1,
        "title": "Best Laptops for Programming in 2024",
        "link": "https://example.com/best-programming-laptops",
        "displayedLink": "https://example.com",
        "snippet": "Looking for the best programming laptops? We've tested and reviewed the top options...",
        "date": "2 days ago",
        "page": 1,
        "sitelinks": {
          "inline": [
            {
              "title": "Specifications",
              "link": "https://example.com/specs"
            }
          ]
        }
      }
    ],
    "peopleAlsoAsk": [
      {
        "question": "What specs should I look for in a programming laptop?",
        "snippet": "Key specifications include RAM, processor, storage, and display quality...",
        "title": "Essential laptop specs for developers",
        "link": "https://example.com/laptop-specs",
        "markdown": "<string>",
        "sources": [
          {
            "label": "Programming Laptop Guide",
            "url": "https://example.com/guide",
            "description": "<string>",
            "position": 123
          }
        ]
      }
    ],
    "peopleAreSaying": [
      {
        "position": 1,
        "title": "Best running shoes 2026 - what runners are saying",
        "link": "https://www.reddit.com/r/running/comments/example/",
        "date": "5 days ago"
      }
    ],
    "relatedSearches": [
      {
        "query": "best budget laptop for coding",
        "link": "https://google.com/search?q=best+budget+laptop+for+coding"
      }
    ],
    "ads": [
      {
        "position": 1,
        "blockPosition": "top",
        "type": "RESULT",
        "title": "Best Programming Laptops - Shop Now",
        "url": "https://example.com/programming-laptops",
        "page": 1,
        "displayedUrl": "example.com/laptops",
        "domain": "example.com",
        "description": "Shop our selection of programming laptops with fast shipping.",
        "category": "Sponsored products",
        "price": {
          "value": 1199,
          "currency": "$"
        },
        "oldPrice": {
          "value": 1299,
          "currency": "$"
        },
        "store": "Apple",
        "imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:...",
        "sitelinks": [
          {
            "url": "https://example.com/gaming-laptops",
            "title": "Gaming Laptops",
            "description": "High-performance laptops for gaming"
          }
        ]
      }
    ],
    "aioverview": {
      "sources": [
        {
          "position": 1,
          "title": "Best Programming Laptops 2024",
          "link": "https://example.com/programming-laptops",
          "snippet": "Comprehensive guide to choosing the perfect laptop for software development"
        }
      ],
      "text": "Based on current information, the best laptops for programming typically include models from Apple MacBook Pro, Dell XPS, and Lenovo ThinkPad series...",
      "markdown": "Based on current information, the best laptops for programming typically include models from Apple MacBook Pro, Dell XPS, and Lenovo ThinkPad series...",
      "videos": [
        {
          "url": "https://www.youtube.com/watch?v=example",
          "title": "Best Laptops for Programming 2024",
          "thumbnail": "https://example.com/thumbnail.jpg",
          "source": "Tech Channel",
          "platform": "YouTube",
          "date": "2 days ago",
          "duration": "12:34"
        }
      ],
      "ads": [
        {
          "position": 1,
          "title": "QA Software Testing Services - On-Demand Software Testing",
          "url": "https://www.testlio.com",
          "domain": "Testlio",
          "description": "Dynamic staffing. Global coverage. Managed manual testing and test automation solutions.",
          "price": {
            "value": 69.99,
            "currency": "$"
          },
          "old_price": {
            "value": 99.99,
            "currency": "$"
          },
          "store": "Best Buy",
          "image": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ..."
        }
      ],
      "html": "<div class=\"ai-overview\">...</div>"
    },
    "shoppingCards": [
      {
        "title": "ASICS Women's Gel-Nimbus 28",
        "productLink": "",
        "category": "More products",
        "price": {
          "value": 169.99,
          "currency": "$"
        },
        "oldPrice": {
          "value": 199.99,
          "currency": "$"
        },
        "store": "DICK'S Sporting Goods",
        "rating": 4.5,
        "reviews": "384",
        "thumbnail": "https://example.com/product.jpg"
      }
    ],
    "html": [
      "https://storage.cloro.dev/results/b83e8dfd-c3a1-4b98-83b9-af91adc21e26/page-1.html"
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.cloro.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Google Search endpoint extracts structured data from Google Search results, including organic results, sponsored ads, People Also Ask questions, related searches, and optional AI Overview data.
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 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
  • 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
  • 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 type for search results. Options: desktop (default), mobile.
  • 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 adds +2 credits. Enabling include.paaAioverview adds +2 credits. Using both adds +4 credits total. Each page beyond the first adds +2 credits (e.g. pages: 3 adds +4, pages: 10 adds +18). See providers for full pricing details.

​
Requesting AI Overview

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

​
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
  }
}

​
Response objects

The response includes the following sections. See each subpage for the full schema and examples.
SectionFieldDescription
Organic resultsresult.organicResultsStandard non-paid search results from Google
Sponsored adsresult.adsPaid ad placements with sitelinks
People Also Askresult.peopleAlsoAskRelated questions with link or AI Overview answers
Related searchesresult.relatedSearchesRelated query suggestions
AI Overviewresult.aioverviewGoogle’s AI-generated summary with sources, videos, and ads (when requested)
result.html is also returned when include.html is true.

​
Usage examples

​
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.

​
City-level geo-targeting

Use location with country to get search results targeted to a specific city or region. The location parameter accepts Google canonical location names: 
{
  "query": "best restaurants",
  "country": "US",
  "location": "New York,New York,United States"
}

​
UULE geo-targeting

For advanced geo-targeting, use uule with a pre-encoded Google UULE string instead of location. This is useful when you generate your own UULE values for precise location control: 
{
  "query": "best restaurants",
  "country": "US",
  "uule": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5"
}
location and uule are mutually exclusive: provide one or the other, not both. Use location for city-level targeting with canonical names, and uule when you need to supply a pre-encoded UULE string.

​
Hydrate People Also Ask with AI Overview content

To get AI-Overview-type People Also Ask items with markdown content and cited sources: 
{
  "query": "best laptops for programming",
  "include": {
    "paaAioverview": true
  }
}
You can combine this with AI Overview extraction: 
{
  "query": "best laptops for programming",
  "include": {
    "aioverview": {
      "markdown": true
    },
    "paaAioverview": 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"

​
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.

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.

Example:

"w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5"

​
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-10)

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