Google Search API 端点

选择一种 Google 搜索类型，并使用 Google Search API 发送对应的请求。本指南在快速开始的基础上展开，涵盖在 Scrapeless API 参考中拥有专门条目的五种搜索类型。

这五种类型都使用相同的 HTTP 端点和 actor scraper.google.search。input.tbm 的取值用于选择搜索类型。

请求与身份验证

POST https://api.scrapeless.com/api/v1/scraper/request
x-api-token: YOUR_API_KEY
Content-Type: application/json

将 YOUR_API_KEY 替换为你的 Scrapeless API 密钥。发送一个包含 actor 和 input 的 JSON 对象。

选择搜索类型

搜索类型	`input.tbm`	请求输入
Google Search	省略	在 `q` 中填入搜索查询
Google Images	`isch`	在 `q` 中填入图片搜索查询
Google Local	`lcl`	在 `q` 中填入本地搜索查询
Google Videos	`vid`	在 `q` 中填入视频搜索查询
Google Shopping	`shop`	在 `q` 中填入购物搜索查询

这些都是同一个端点的搜索模式。切换模式时，请保持 HTTP URL、身份验证请求头和 actor 不变。

Google Search

对于常规网页搜索，省略 tbm。

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actor": "scraper.google.search",
  "input": {
    "q": "coffee",
    "hl": "en",
    "gl": "us"
  }
}'

快速开始中包含一个带有 organic_results、pagination 及其他依赖查询的部分的网页搜索响应。请勿假设每个查询都会返回全部部分。

Google Search 参考

Google Images

将 tbm 设置为 isch 以请求图片搜索。下面的请求使用默认的 Google 域名。

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actor": "scraper.google.search",
  "input": {
    "q": "Apple Iphone16",
    "hl": "en",
    "gl": "us",
    "tbm": "isch"
  }
}'

Google Images 参考

Google Local

将 tbm 设置为 lcl 以请求本地搜索。

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actor": "scraper.google.search",
  "input": {
    "q": "coffee shops",
    "hl": "en",
    "gl": "us",
    "tbm": "lcl"
  }
}'

如需按城市级别定位，请在 input 中添加 location，例如 "Austin, Texas, United States"。请使用 location 或 uule 其中之一，切勿在同一个请求中同时使用两者。

对于本地搜索分页，start 必须是 20 的倍数：0、20、40，依此类推。

Google Local 参考

Google Videos

将 tbm 设置为 vid。此示例保留了专门 API 参考中所示的请求字段。

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actor": "scraper.google.search",
  "input": {
    "engine": "google.search",
    "q": "Coffee",
    "google_domain": "google.com",
    "start": 0,
    "num": 10,
    "tbm": "vid"
  }
}'

Google Videos 参考

Google Shopping

将 tbm 设置为 shop。此示例保留了专门 API 参考中所示的请求字段。

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actor": "scraper.google.search",
  "input": {
    "engine": "google.search",
    "q": "Coffee",
    "google_domain": "google.com",
    "start": 0,
    "num": 10,
    "tbm": "shop"
  }
}'

Google Shopping 参考

通用搜索控制项

在 input 中设置以下字段：

参数	用途
`q`	必填的搜索查询。
`gl`	搜索国家/地区，例如 `us`。
`hl`	搜索语言，例如 `en`。
`google_domain`	Google 域名；默认为 `google.com`。
`location`	搜索来源地，最好指定到城市级别。
`uule`	编码后的 Google 位置；与 `location` 互斥。
`start`	结果偏移量。网页搜索使用 `0`、`10`、`20`，依此类推。
`num`	请求的最大结果数量。
`tbs`	高级搜索过滤器。

参数参考中提醒，num 可能会增加延迟或影响特定的结果类型。除非需要，否则请省略该参数；请求的数量并不保证会返回相应数量的结果。上面的 Videos 和 Shopping 示例保留了文档中所记录的取值 10。

完整的参数说明请参阅 Google Search 参数。当前那里列出的设备支持为桌面端。

读取结果

HTTP 200：读取 JSON 结果。
HTTP 201：保存 taskId，并使用结果端点检索已存在的任务。

curl --request GET 'https://api.scrapeless.com/api/v1/scraper/result/YOUR_TASK_ID' \
  --header 'x-api-token: YOUR_API_KEY'

将 YOUR_TASK_ID 替换为返回的 ID。完整流程请参阅结果与轮询。

响应中包含的部分会因搜索类型和查询而异。专门的 API 规范目前对成功响应声明为一个通用对象；常规 Google Search 示例并不是 Images、Local、Videos 或 Shopping 的 schema。