SukidataSukidata

WEB DATA

Google 搜索

根据关键词、位置、语言和设备获取结构化 Google 搜索结果。

POSThttps://api.sukidata.com/v1/serp

快速开始

发送请求

在 Authorization 请求头中发送 API Key，并以 JSON 格式传入搜索参数。

cURL
curl --request POST \
  --url https://api.sukidata.com/v1/serp \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "q": "coffee shops in seattle",
    "location": "Seattle, Washington, United States",
    "hl": "en",
    "device": "desktop"
  }'

在 Playground 中试用 →

请求体

常用参数

q字符串 · 必填

搜索关键词，支持 site:、inurl: 和 intitle: 等 Google 搜索运算符。

location字符串

受支持的 Google 位置名称或 ID。可以使用位置查询端点查找准确值。

google_domain gl hl字符串

Google 域名、两位国家或地区代码与界面语言，默认值为 google.com、us 和 en。

device字符串

可选 desktop、tablet 或 mobile，默认值为 desktop。

tbm字符串

Google 结果类型，包括图片、本地、视频、新闻、购物和专利；普通网页搜索无需填写。

start整数

从零开始的结果偏移量，默认值为 0。

async布尔值

设为 true 时立即返回搜索 ID，稍后查询结果；默认为 false。

在 API 参考中查看全部 Google 搜索参数

响应

结构化搜索结果

完成的响应会包含搜索元数据，以及 Google 页面实际出现的结果分组。

响应示例
{
  "search_metadata": {
    "id": "serp_example",
    "status": "Success",
    "created_at": "2026-09-22T00:00:00Z",
    "total_time_taken": 1.2
  },
  "search_parameters": {
    "engine": "google",
    "q": "coffee shops in seattle",
    "google_domain": "google.com",
    "gl": "us",
    "hl": "en",
    "device": "desktop"
  },
  "search_information": {
    "query_displayed": "coffee shops in seattle",
    "total_results": 1250000
  },
  "organic_results": [
    {
      "position": 1,
      "title": "Seattle Coffee Guide",
      "link": "https://example.com/seattle-coffee",
      "snippet": "Discover neighborhood coffee shops in Seattle."
    }
  ]
}
search_metadata请求状态、标识、耗时和结果文件链接。
search_parameters本次搜索实际使用的标准化参数。
organic_results带标题、链接和摘要的自然搜索结果。
answer_box knowledge_graphGoogle 返回时提供的增强结果模块。
local_results top_stories本地和新闻结果模块。
pagination后续结果页可用的导航信息。
请求仍在处理？同步请求等待结束后也可能返回 Queued 或 Processing。将 search_metadata.id 用于 GET /v1/serp/{search_id}，继续查询至 Success 或 Error。查询进度无需重新提交搜索。成功的搜索也可能没有自然搜索结果。

计费

积分消耗

Google 搜索使用 Web Data 积分，最终费用以 X-Sukidata-Credits-Used 为准。单价与免费响应规则见 Web Data 计费说明。

请求遇到问题？请将 X-Request-ID 响应头一并发送至 support@sukidata.com。

处理错误

  • 400：检查 q 是否为空，以及参数取值是否有效。
  • 401：检查 API Key；402：补充 Web Data 积分。
  • 503：服务暂时不可用，稍后再试。

HTTP 200 响应也需要检查 search_metadata.status。Error 表示搜索失败，error 对象中包含错误码和说明。