Google 搜索

Google 通用网页 SERP，支持关键词检索、地区/语言定向和高级过滤参数。

本页给出 Google 搜索的字段定义、参数分组、必填约束以及可用过滤参数。

元数据

字段	值
引擎名称	Google 搜索
原始名称	Google Search
内部标识（scraper）	`google_search`
接口标识（engine）	`google_search`
网站	Google
网站地址	Google.com
输出格式	`json`
版本	`1.0.0`
参数数量	`19`
参数分组	搜索词 (1), 地区与语言 (5), 高级参数 (6), 高级筛选 (3), 地理位置 (2), 分页 (1), 请求控制 (1)

请求示例

下面的请求体是本次文档更新时实际用于验证 google_search 的请求。对于 /v1/serp，engine 字段应传当前引擎的 scraper 值。

curl -X POST "https://run.xcrawl.com/v1/serp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine":"google_search","q":"openai"}'

响应示例

下面的 JSON 片段来自同一次真实响应。为了避免页面被超长字段淹没，超长字符串、data URL 和大型数组做了裁剪。

{
  "search_metadata": {
    "cached": true,
    "created_at": "2026-03-26 08:24:18 UTC",
    "id": "01KMMKX1EC62VPCD7FW8YZ8QVS",
    "json_endpoint": "https://serp.xcrawl.com/01KMMKX1EC62VPCD7FW8YZ8QVS.json",
    "processed_at": "2026-03-26 08:24:18 UTC",
    "raw_html_file": "https://serp.xcrawl.com/01KMMKX1EC62VPCD7FW8YZ8QVS.html",
    "status": "completed",
    "total_time_taken": 2
  },
  "search_parameters": {
    "engine": "google_search",
    "q": "openai"
  },
  "total_credits_used": 1,
  "ads": [
    {
      "block_position": "top",
      "description": "Official ChatGPT website — The ultimate how-to guide for your unique interests. Ask the official ChatGPT today. ChatGPT can help with book ideas, poems, or trip planning. Try it yourself. Shop smarter with ChatGPT.",
      "displayed_link": "https://chatgpt.com/",
      "link": "https://chatgpt.com/",
      "position": 3,
      "sitelinks": [],
      "source": "ChatGPT",
      "title": "Official ChatGPT from OpenAI",
      "tracking_link": "https://www.google.com/aclk?sa=L&pf=1&ai=DChsSEwih5qTvkI2SAxWGJtQBHV99Ch0YACICCAEQAxoCb2E&co=1&ase=2&gclid=EAIaIQobChMIoeak75CNkgMVhibUAR1ffQodEAAYASAAEgI0gvD_BwE&cid=CAAS0wHkaL0sW3DTIjSZ4Aae3ZqxOJQZNXFVmv08yvggeJu9P9TRL... [truncated, 556 chars]"
    },
    {
      "_note": "1 more items omitted"
    }
  ],
  "immersive_products": [],
  "knowledge_graph": {
    "entity_type": "food, kp3_verticals",
    "header_images": [
      {
        "image": "data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOw... [truncated data URL, 82 chars]"
      },
      {
        "_note": "3 more items omitted"
      }
    ],
    "kgmid": "/m/02vqfm",
    "knowledge_graph_search_link": "https://www.google.co.US/search?kgmid=/m/02vqfm&hl=en-US&q=openai"
  },
  "local_map": {
    "gps_coordinates": {},
    "image": "data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOw... [truncated data URL, 82 chars]"
  },
  "organic_results": [
    {
      "displayed_link": "https://openai.com",
      "favicon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABwAAAAcCAAAAABXZoBIAAABEElEQVR4Ab... [truncated data URL, 462 chars]",
      "link": "https://openai.com/",
      "position": 1,
      "redirect_link": "https://www.google.com/url?sa=t&source=web&rct=j&opi=89978449&url=https://openai.com/&ved=2ahUKEwi9nfzhl4KPAxWfSDABHTPgIkYQFnoECD4QAQ",
      "snippet": "We believe our research will eventually lead to artificial general intelligence, a system that can solve human-level problems. Building safe and beneficial ...",
      "snippet_highlighted_words": null,
      "source": "OpenAI",
      "thumbnail": "",
      "title": "OpenAI"
    },
    {
      "_note": "3 more items omitted"
    }
  ],
  "pagination": {
    "current": "1",
    "next": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=10&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
    "other_pages": {
      "2": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=10&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "3": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=20&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "4": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=30&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "5": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=40&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "6": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=50&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "7": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=60&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "8": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=70&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "9": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=80&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "10": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=90&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]"
    }
  },
  "refine_search_filters": [
    {
      "question": "Is OpenAI owned by Elon Musk?"
    },
    {
      "_note": "3 more items omitted"
    }
  ],
  "refine_this_search": [],
  "related_searches": [
    {
      "block_position": 1,
      "link": "https://www.google.com/search?sca_esv=3087728c2f704245&hl=en&q=OpenAI+chat&sa=X&ved=2ahUKEwiipaHikb2TAxWEv4kEHfe3GegQ1QJ6BAg-EAE",
      "query": "OpenAI chat"
    },
    {
      "_note": "7 more items omitted"
    }
  ]
}

必填参数

以下表格列出当前 metadata 中标记为 must: true 的字段。字段是否必填，以 properties.<field>.must 为准，不以顶层 required 数组为准。

参数	类型	分组	说明
`q`	`string`	搜索词	你想让搜索引擎检索的关键词或短语。

可用参数

以下内容按后端返回的字段分组展示。主表只保留字段名、类型、必填标记和字段说明；默认值、可选值等附加约束会列在每个分组后。

搜索词

参数	类型	必填	说明
`q`	`string`	是	你想让搜索引擎检索的关键词或短语。

地区与语言

参数	类型	必填	说明
`cr`	`string`	否	将结果限制在一个或多个国家范围内。
`gl`	`string`	否	用于本地化搜索结果的国家或地区代码。
`hl`	`string`	否	用于控制搜索界面和结果标签语言的参数。
`lr`	`string`	否	将结果限制在一个或多个语言范围内。
`google_domain`	`string`	否	要请求的 Google 域名，例如 `google.com` 或 `google.co.uk`。

附加约束

gl：可选值：243 个可选值，例如：af、al、dz、as、ad
hl：可选值：157 个可选值，例如：af、ak、sq、ws、am
google_domain：可选值：47 个可选值，例如：google.com、google.com.hk、google.co.uk、google.co.jp、google.us

高级参数

参数	类型	必填	说明
`si`	`string`	否	复用 Google 返回的结果状态令牌，用于打开特定结果布局或标签页。
`ibp`	`string`	否	Google 的布局参数，可用于展开或渲染某些特殊结果模块。
`uds`	`string`	否	Google 的筛选令牌，用于应用某个建议筛选条件。
`lsig`	`string`	否	Google 的附加地点令牌，在本地结果或知识面板场景中可能需要。
`kgmid`	`string`	否	Google Knowledge Graph 实体 ID，用于定位特定实体。
`ludocid`	`string`	否	Google 的地点或商家 CID，用于定位特定本地实体。

高级筛选

参数	类型	必填	说明
`tbs`	`string`	否	Google 的高级筛选字符串，常用于时间或内容过滤。
`nfpr`	`boolean`	否	尽量关闭自动纠错结果，优先保留原始查询词。
`filter`	`boolean`	否	控制是否启用相似结果或重复结果过滤。

附加约束

nfpr：默认值：false
filter：默认值：false

地理位置

参数	类型	必填	说明
`uule`	`string`	否	Google 使用的编码位置字符串，可用于更精细的地理定向。
`location`	`string`	否	用于让结果更贴近目标地区的地理位置提示。

附加约束

location：可选值：10 个可选值，例如：IN、US、BR、ID、MX

分页

参数	类型	必填	说明
`start`	`number`	否	Google 风格分页使用的结果偏移量。

附加约束

start：默认值：0

请求控制

参数	类型	必填	说明
`no_cache`	`boolean`	否	跳过缓存结果并强制重新抓取。

附加约束

no_cache：默认值：false

SERP

引擎列表

Data

API 列表

Google 搜索

元数据

请求示例

响应示例

必填参数

可用参数

搜索词

地区与语言

附加约束

高级参数

高级筛选

附加约束

地理位置

附加约束

分页

附加约束

请求控制

附加约束