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",
  "city": "New York",
  "pages": 3,
  "include": {
    "html": false,
    "aioverview": 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",
        "sitelinks": {
          "inline": [
            {
              "title": "Specifications",
              "link": "https://example.com/specs"
            }
          ]
        }
      }
    ],
    "peopleAlsoAsk": [
      {
        "question": "What specs should I look for in a programming laptop?",
        "type": "AIOVERVIEW",
        "snippet": "Key specifications include RAM, processor, storage, and display quality...",
        "title": "Essential laptop specs for developers",
        "link": "https://example.com/laptop-specs"
      }
    ],
    "relatedSearches": [
      {
        "query": "best budget laptop for coding",
        "link": "https://google.com/search?q=best+budget+laptop+for+coding"
      }
    ],
    "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..."
    },
    "html": "<html>...</html>"
  }
}

​
Overview

The Google Search endpoint extracts structured data from Google Search results, including organic results, People Also Ask questions, related searches, and optional AI Overview data.

​
Request parameters

Uses common parameters. Google-specific options:
  • country (string): ISO 3166-1 alpha-2 country code for localized results. Defaults to US
  • city (string): Canonical city name for hyperlocal search results. Use canonical city names from the Google Ads geotargets.
  • pages (integer): Number of search results pages to scrape (1-20). Defaults to 1
  • include.html (boolean): Include raw HTML response. Defaults to false
  • include.aioverview (boolean|object): Include Google AI Overview. Use object with markdown: true for markdown formatting. Defaults to false

​
Response schema

Includes common response fields plus:
FieldTypeDescription
result.organicResultsarrayOrganic search results with position, title, link, snippet
result.peopleAlsoAskarray”People Also Ask” questions with answers
result.relatedSearchesarrayRelated search suggestions
result.aioverviewobjectGoogle AI Overview data (if requested)
result.aioverview.textstringAI Overview text content
result.aioverview.sourcesarraySources referenced in AI Overview
result.aioverview.markdownstringAI Overview in markdown format (if requested)
result.htmlstringRaw HTML response (if requested)

​
Usage examples

​
Hyperlocal search with city parameter

{
  "query": "restaurants near me",
  "city": "New York"
}

{
  "query": "best coffee shops",
  "city": "Paris,Île-de-France"
}

{
  "query": "hotels near me",
  "city": "Tokyo,Tokyo,Japan"
}
Use the city parameter to get hyperlocal search results for specific locations. The backend automatically converts canonical city names to Google’s location parameter. City name formats supported:
  • City only: “New York”, “Paris”, “Tokyo”
  • City with region: “Paris,Île-de-France”, “New York,New York”
  • City with region and country: “Tokyo,Tokyo,Japan”, “London,England,United Kingdom”
Use canonical city names from the Google Ads geotargets.

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

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"

​
city
string

Canonical city name for hyperlocal search results. Use canonical city names from the Google Ads geotargets

Example:

"New York"

​
pages
integer
default:1

Number of search results pages to scrape (1-20)

Required range: 1 <= x <= 20
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