SearchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/snoopscan-com/json-schema/snoopscan-com-search-request-schema.json",
  "title": "SearchRequest",
  "description": "Search the web. Filters after `location` are optional; when set, every result matches.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/snoopscan-com-openapi.json#/components/schemas/SearchRequest",
  "properties": {
    "query": {
      "type": "string",
      "title": "Query",
      "description": "What to search for."
    },
    "limit": {
      "type": "integer",
      "maximum": 50.0,
      "minimum": 1.0,
      "title": "Limit",
      "description": "How many results, 1 to 50.",
      "default": 10
    },
    "sources": {
      "items": {
        "type": "string",
        "enum": [
          "web",
          "news",
          "images"
        ]
      },
      "type": "array",
      "title": "Sources",
      "description": "Which kinds of result: `web`, `news`, `images`."
    },
    "location": {
      "anyOf": [
        {
          "$ref": "#/$defs/Location"
        },
        {
          "type": "null"
        }
      ],
      "description": "The country to search from, which changes the results, e.g. `{\"country\": \"GB\"}`."
    },
    "scrapeOptions": {
      "anyOf": [
        {
          "$ref": "#/$defs/ScrapeOptions"
        },
        {
          "type": "null"
        }
      ],
      "description": "Also fetch every result page with these options. Each page fetched is charged like a scrape."
    },
    "place": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Place",
      "description": "Where the searcher is standing, in free text, e.g. \"Austin, Texas, United States\". Finer than `location`."
    },
    "language": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 8,
          "minLength": 2
        },
        {
          "type": "null"
        }
      ],
      "title": "Language",
      "description": "The language results should be in, e.g. `en`."
    },
    "device": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "desktop",
            "mobile"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Device",
      "description": "`desktop` or `mobile`. Mobile results can differ from desktop ones."
    },
    "freshness": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "hour",
            "day",
            "week",
            "month",
            "year"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Freshness",
      "description": "Only results from the last `hour`, `day`, `week`, `month` or `year`."
    },
    "safeSearch": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "off",
            "moderate",
            "strict"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Safesearch",
      "description": "`off`, `moderate` or `strict`."
    },
    "page": {
      "type": "integer",
      "maximum": 100.0,
      "minimum": 1.0,
      "title": "Page",
      "description": "Which page of results, starting at 1.",
      "default": 1
    },
    "autoCorrect": {
      "type": "boolean",
      "title": "Autocorrect",
      "description": "Set `false` to search the query exactly as typed, e.g. a part number or a brand name.",
      "default": true
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "query"
  ],
  "$defs": {
    "CaptchaCheckboxAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "captchaCheckbox",
          "title": "Type"
        },
        "frameSelector": {
          "type": "string",
          "title": "Frameselector",
          "default": "iframe[src*=\"/recaptcha/\"][src*=\"/anchor\"]"
        },
        "selector": {
          "type": "string",
          "title": "Selector",
          "default": "#recaptcha-anchor"
        },
        "successSelector": {
          "type": "string",
          "minLength": 1,
          "title": "Successselector"
        },
        "timeoutMs": {
          "type": "integer",
          "maximum": 15000.0,
          "minimum": 500.0,
          "title": "Timeoutms",
          "default": 8000
        },
        "captureEvidence": {
          "type": "boolean",
          "title": "Captureevidence",
          "description": "Return a screenshot from before and after the click.",
          "default": false
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type",
        "successSelector"
      ],
      "title": "CaptchaCheckboxAction",
      "description": "Click a challenge checkbox once, then wait for `successSelector` to appear."
    },
    "ChangeTrackingFormat": {
      "properties": {
        "type": {
          "type": "string",
          "const": "changeTracking",
          "title": "Type"
        },
        "modes": {
          "items": {
            "type": "string",
            "enum": [
              "git-diff",
              "json"
            ]
          },
          "type": "array",
          "title": "Modes"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ChangeTrackingFormat"
    },
    "ClickAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "click",
          "title": "Type"
        },
        "selector": {
          "type": "string",
          "title": "Selector"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type",
        "selector"
      ],
      "title": "ClickAction"
    },
    "ExecuteJavascriptAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "executeJavascript",
          "title": "Type"
        },
        "script": {
          "type": "string",
          "title": "Script"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type",
        "script"
      ],
      "title": "ExecuteJavascriptAction"
    },
    "JsonFormat": {
      "properties": {
        "schema": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Schema",
          "description": "Your own JSON Schema for the fields you want. Give this or `template`, not both."
        },
        "template": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Template",
          "description": "A named template instead of a schema — `product`, `article`, `jobPosting` and more. GET /v1/templates lists them with their fields."
        },
        "type": {
          "type": "string",
          "const": "json",
          "title": "Type"
        },
        "prompt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type"
      ],
      "title": "JsonFormat"
    },
    "Location": {
      "properties": {
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2,
          "title": "Country"
        },
        "languages": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Languages"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "country"
      ],
      "title": "Location"
    },
    "PressAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "press",
          "title": "Type"
        },
        "key": {
          "type": "string",
          "title": "Key"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type",
        "key"
      ],
      "title": "PressAction"
    },
    "ProxyMode": {
      "type": "string",
      "enum": [
        "none",
        "datacenter",
        "residential",
        "mobile",
        "auto"
      ],
      "title": "ProxyMode"
    },
    "ScrapeAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "scrape",
          "title": "Type"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ScrapeAction"
    },
    "ScrapeOptions": {
      "properties": {
        "formats": {
          "items": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "markdown",
                  "html",
                  "rawHtml",
                  "links",
                  "media",
                  "summary",
                  "screenshot",
                  "json",
                  "network"
                ]
              },
              {
                "$ref": "#/$defs/ScreenshotFormat"
              },
              {
                "$ref": "#/$defs/JsonFormat"
              },
              {
                "$ref": "#/$defs/ChangeTrackingFormat"
              }
            ]
          },
          "type": "array",
          "title": "Formats",
          "description": "What to return: `markdown`, `html`, `rawHtml`, `links`, `media`, `summary`, `screenshot`, or a `json` object carrying your schema. Ask for several in one call."
        },
        "onlyMainContent": {
          "type": "boolean",
          "title": "Onlymaincontent",
          "description": "Return the article and drop navigation, headers, footers and cookie banners. Turn it off to keep the whole page.",
          "default": true
        },
        "includeTags": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Includetags",
          "description": "CSS selectors to keep even when they sit outside the main content."
        },
        "excludeTags": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Excludetags",
          "description": "CSS selectors to drop before the page is read."
        },
        "maxAge": {
          "type": "integer",
          "minimum": 0.0,
          "title": "Maxage",
          "description": "Serve a cached copy if one was taken within this many milliseconds. A cache hit costs nothing. Set `0` to force a fresh fetch.",
          "default": 0
        },
        "storeInCache": {
          "type": "boolean",
          "title": "Storeincache",
          "description": "Keep this response in the cache so a later request can be served free.",
          "default": true
        },
        "waitFor": {
          "type": "integer",
          "maximum": 120000.0,
          "minimum": 0.0,
          "title": "Waitfor",
          "description": "Milliseconds to wait after the page loads before reading it, for content that loads late. Renders the page in a browser, and is billed as a browser page.",
          "default": 0
        },
        "timeout": {
          "type": "integer",
          "maximum": 300000.0,
          "minimum": 1000.0,
          "title": "Timeout",
          "description": "Give up on this request after this many milliseconds.",
          "default": 90000
        },
        "actions": {
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/WaitAction"
              },
              {
                "$ref": "#/$defs/ClickAction"
              },
              {
                "$ref": "#/$defs/CaptchaCheckboxAction"
              },
              {
                "$ref": "#/$defs/WriteAction"
              },
              {
                "$ref": "#/$defs/PressAction"
              },
              {
                "$ref": "#/$defs/ScrollAction"
              },
              {
                "$ref": "#/$defs/ScreenshotAction"
              },
              {
                "$ref": "#/$defs/ScrapeAction"
              },
              {
                "$ref": "#/$defs/ExecuteJavascriptAction"
              }
            ]
          },
          "type": "array",
          "title": "Actions",
          "description": "Steps to run in a browser before the page is read: click, type, scroll, wait or `captchaCheckbox`. A `captchaCheckbox` step needs `successSelector`."
        },
        "captchaHandling": {
          "type": "string",
          "enum": [
            "auto",
            "off"
          ],
          "title": "Captchahandling",
          "description": "Click a challenge checkbox once if one appears. Set `off` to never click.",
          "default": "auto"
        },
        "captchaEvidence": {
          "type": "boolean",
          "title": "Captchaevidence",
          "description": "Return screenshots from before and after an automatic checkbox click.",
          "default": false
        },
        "headers": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object",
          "title": "Headers",
          "description": "Extra headers to send. `User-Agent` and other browser-identity headers are set for you and cannot be changed."
        },
        "mobile": {
          "type": "boolean",
          "title": "Mobile",
          "description": "Read the page as a phone would see it.",
          "default": false
        },
        "location": {
          "anyOf": [
            {
              "$ref": "#/$defs/Location"
            },
            {
              "type": "null"
            }
          ],
          "description": "Fetch from a country, in its language, e.g. `{\"country\": \"US\"}`."
        },
        "proxy": {
          "$ref": "#/$defs/ProxyMode",
          "description": "Leave on `auto` and the route is chosen for you.",
          "default": "auto"
        },
        "blockAssets": {
          "type": "boolean",
          "title": "Blockassets",
          "description": "Skip images, fonts and media when the page is rendered in a browser. Faster.",
          "default": true
        },
        "removeBase64Images": {
          "type": "boolean",
          "title": "Removebase64Images",
          "description": "Strip inline base64 images out of the returned markdown and HTML.",
          "default": true
        },
        "parsers": {
          "items": {
            "type": "string",
            "const": "pdf"
          },
          "type": "array",
          "title": "Parsers",
          "description": "Which document parsers may run, for example `pdf`."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "ScrapeOptions",
      "description": "How a page is fetched and what comes back: every /v1/scrape field except `url`."
    },
    "ScreenshotAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "screenshot",
          "title": "Type"
        },
        "fullPage": {
          "type": "boolean",
          "title": "Fullpage",
          "default": false
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ScreenshotAction"
    },
    "ScreenshotFormat": {
      "properties": {
        "type": {
          "type": "string",
          "const": "screenshot",
          "title": "Type"
        },
        "fullPage": {
          "type": "boolean",
          "title": "Fullpage",
          "default": false
        },
        "quality": {
          "type": "integer",
          "maximum": 100.0,
          "minimum": 1.0,
          "title": "Quality",
          "default": 80
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ScreenshotFormat"
    },
    "ScrollAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "scroll",
          "title": "Type"
        },
        "direction": {
          "type": "string",
          "enum": [
            "up",
            "down"
          ],
          "title": "Direction",
          "default": "down"
        },
        "amount": {
          "type": "integer",
          "maximum": 50.0,
          "minimum": 1.0,
          "title": "Amount",
          "default": 1
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type"
      ],
      "title": "ScrollAction"
    },
    "WaitAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "wait",
          "title": "Type"
        },
        "milliseconds": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Milliseconds"
        },
        "selector": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Selector"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type"
      ],
      "title": "WaitAction"
    },
    "WriteAction": {
      "properties": {
        "type": {
          "type": "string",
          "const": "write",
          "title": "Type"
        },
        "selector": {
          "type": "string",
          "title": "Selector"
        },
        "text": {
          "type": "string",
          "title": "Text"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type",
        "selector",
        "text"
      ],
      "title": "WriteAction"
    }
  }
}