{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cloro-dev/json-schema/cloro-dev-google-monitor-request-schema.json",
  "title": "GoogleMonitorRequest",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cloro-dev-openapi.json#/components/schemas/GoogleMonitorRequest",
  "anyOf": [
    {
      "required": [
        "query",
        "country"
      ]
    },
    {
      "required": [
        "query",
        "gl"
      ]
    },
    {
      "required": [
        "url"
      ]
    }
  ],
  "type": "object",
  "properties": {
    "query": {
      "description": "The search query to execute on Google. Required unless you supply 'url' instead — the two are mutually exclusive.",
      "type": "string",
      "minLength": 1,
      "maxLength": 10000
    },
    "url": {
      "description": "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).",
      "type": "string",
      "format": "uri"
    },
    "country": {
      "$ref": "#/$defs/CountryCode",
      "description": "ISO 3166-1 alpha-2 country code for localized search results. See [List of countries](/api-reference/endpoint/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'."
    },
    "gl": {
      "$ref": "#/$defs/GlParameter"
    },
    "hl": {
      "$ref": "#/$defs/HlParameter"
    },
    "location": {
      "description": "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.",
      "type": "string"
    },
    "uule": {
      "description": "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.",
      "type": "string"
    },
    "device": {
      "description": "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.",
      "type": "string",
      "enum": [
        "desktop",
        "mobile",
        "ios",
        "android"
      ],
      "default": "desktop"
    },
    "pages": {
      "description": "Number of search results pages to scrape (1-10). Paid add-on: +2 credits per page after the first ([pricing](/guides/providers#google-search-multi-page-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).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 1
    },
    "include": {
      "description": "Optional flags for including additional response data",
      "type": "object",
      "properties": {
        "html": {
          "description": "Include raw HTML response from Google search",
          "type": "boolean",
          "default": false
        },
        "aioverview": {
          "description": "Include Google AI Overview in the response. `true`, `{}` and `{\"markdown\": false}` return the AI Overview without `markdown`. Send `{\"markdown\": true}` to also get `result.aioverview.markdown`. Paid add-on: one flat +2 credits covers `aioverview` and `paaAioverview`, alone or together ([pricing](/guides/providers#google-search-multi-page-pricing)).",
          "type": "object",
          "properties": {
            "markdown": {
              "description": "Include AI Overview formatted as markdown in `result.aioverview.markdown`. Only `true` turns it on.",
              "type": "boolean",
              "default": false
            }
          },
          "default": {
            "markdown": false
          },
          "additionalProperties": false
        },
        "paaAioverview": {
          "description": "Hydrate AI-Overview-type People Also Ask items with markdown content and sources. Paid add-on: one flat +2 credits covers `aioverview` and `paaAioverview`, alone or together ([pricing](/guides/providers#google-search-multi-page-pricing)). Each hydrated item adds one scraper fetch (typically 1-2 per page), so responses take longer.",
          "type": "boolean",
          "default": false
        },
        "googleGoto": {
          "description": "Ignored since 8th September 2026. Every redirect link now ships as `redirectLink` beside its destination, so both are returned without this flag. Requests still sending it behave as if it were absent.",
          "type": "boolean",
          "default": false,
          "deprecated": true
        }
      },
      "default": {
        "html": false
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false,
  "$defs": {
    "CountryCode": {
      "description": "ISO 3166-1 alpha-2 country code.",
      "type": "string",
      "enum": [
        "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"
      ]
    },
    "GlParameter": {
      "description": "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`.",
      "type": "string"
    },
    "HlParameter": {
      "description": "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.",
      "type": "string"
    }
  }
}