API Reference › Monitor › Monitor Google Search

Monitor Google Search

Submit a search query and receive a structured snapshot of a live Google results page, with organic listings, related questions, ads, and other blocks parsed into JSON.

POST https://api.cloro.cloud/v1/monitor/google

Overview

This endpoint runs a single Google search on cloro's infrastructure and returns the rendered result page decomposed into typed sections. You control the query, the target country, and optional geo-targeting down to city level, and cloro handles localization, paging, and parsing. Authenticate with a bearer token in the Authorization header and send a JSON body.

Use location for a human-readable place name or uule for a pre-computed Google UULE value. These two options are mutually exclusive — supply exactly one when you need geo-targeting beyond the country level.

Request parameters

Field	Type	Description
`query`	string, required	The search term to run on Google. Length 1–10000 characters.
`country`	string, required	ISO 3166-1 alpha-2 country code that localizes the results, e.g. `US`.
`location`	string	Google canonical location name in `City,Region,Country` form for city-level targeting. Pair with `country`. Cannot be combined with `uule`.
`uule`	string	A pre-encoded Google UULE string for exact geo-targeting when you already hold the encoded value. Cannot be combined with `location`.
`device`	enum<string>	Device profile for the search. One of `desktop` or `mobile`. Defaults to `desktop`.
`pages`	integer	How many result pages to collect, from 1 to 10. Defaults to `1`.
`include`	object	Flags for optional extras. `html` attaches the raw page HTML, `aioverview.markdown` returns the AI overview as markdown, and `paaAioverview` enriches People-Also-Ask entries with AI overview content.

Response fields

Field	Type	Description
`success`	boolean	Indicates whether the search completed successfully.
`result`	object	Container for the parsed page. Holds `organicResults`, `peopleAlsoAsk`, `peopleAreSaying`, `relatedSearches`, and `ads`.
`result.organicResults[]`	array	Standard listings with `position`, `title`, `link`, `displayedLink`, `snippet`, `date`, `page`, and any `sitelinks`.
`result.peopleAlsoAsk[]`	array	Related questions, each with a `snippet`, source `link`, optional `markdown`, and a `sources` list.
`result.ads[]`	array	Sponsored placements including `blockPosition`, `domain`, pricing objects, and merchant details.

Response example

{
  "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": "Our team benchmarked the leading models for developers...",
        "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": "The essentials are memory, CPU, storage, and screen quality...",
        "title": "Essential laptop specs for developers",
        "link": "https://example.com/laptop-specs",
        "sources": [
          {
            "label": "Programming Laptop Guide",
            "url": "https://example.com/guide",
            "position": 1
          }
        ]
      }
    ],
    "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",
        "domain": "example.com",
        "description": "Fast shipping on our full range of developer laptops.",
        "price": { "value": 1199, "currency": "$", "raw": "$1,199" }
      }
    ]
  }
}

Notes

Responses may return status codes including 400, 401, 403, 404, 409, 429, and 500. A 429 signals rate limiting — retry after a short back-off. For larger workloads, prefer the asynchronous task endpoints so requests are queued and polled rather than held open. Questions? Reach us at [email protected].