Google Shopping 搜索

Google Shopping SERP，支持商品检索、价格区间、排序和商家筛选参数。

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

元数据

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

请求示例

下面的请求体是本次文档更新时实际用于验证 google_shopping_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_shopping_search","q":"wireless mouse"}'

响应示例

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

{
  "search_metadata": {
    "cached": true,
    "created_at": "2026-03-26 08:18:04 UTC",
    "id": "01KMMKHBTF1XC6B3XV67SE07FA",
    "json_endpoint": "https://serp.xcrawl.com/01KMMKHBTF1XC6B3XV67SE07FA.json",
    "processed_at": "2026-03-26 08:18:04 UTC",
    "raw_html_file": "https://serp.xcrawl.com/01KMMKHBTF1XC6B3XV67SE07FA.html",
    "status": "completed",
    "total_time_taken": 10
  },
  "search_parameters": {
    "engine": "google_shopping_search",
    "q": "wireless mouse"
  },
  "total_credits_used": 1,
  "filters": [
    {
      "input_type": "input_type",
      "options": [
        {
          "link": "https://www.google.com/search?udm=28&q=wireless+mouse+nearby&hl=en&gl=us&shoprs=CAEYAyoOd2lyZWxlc3MgbW91c2UyDAgDEgZOZWFyYnkYAljZ8yBgAg&sa=X&ved=2ahUKEwiUlfCtkL2TAxWwIEQIHdSIEfUQ268JKAB6BAgLEAQ",
          "text": "Nearby"
        },
        {
          "_note": "3 more items omitted"
        }
      ],
      "type": "Refine results"
    }
  ],
  "serpapi_pagination": {
    "next": "https://www.google.com/search?udm=28&q=wireless mouse&hl=en&gl=us&start=10"
  },
  "shopping_results": [
    {
      "delivery": "15-day returns",
      "extracted_old_price": "50",
      "extracted_price": "26.99",
      "multiple_sources": true,
      "old_price": "$50",
      "price": "$26.99",
      "rating": "4.6",
      "reviews": "11K",
      "source": "Best Buy",
      "source_icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAABa0lEQVRYhe... [truncated data URL, 582 chars]",
      "_note": "3 more fields omitted"
    },
    {
      "_note": "39 more items omitted"
    }
  ]
}

必填参数

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

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

可用参数

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

搜索词

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

地区与语言

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

附加约束

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

分页

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

附加约束

num：默认值：0
start：默认值：0

地理位置

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

附加约束

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

高级筛选

参数	类型	必填	说明
`shoprs`	`string`	否	Search Filter Token 参数。
`on_sale`	`boolean`	否	On Sale 参数。
`sort_by`	`number`	否	Sort By 参数。
`max_price`	`number`	否	Max Price 参数。
`min_price`	`number`	否	Min Price 参数。
`free_shipping`	`boolean`	否	Free Shipping 参数。
`small_business`	`boolean`	否	Small Business 参数。

附加约束

on_sale：默认值：false
sort_by：默认值：1；可选值：2 个可选值，例如：1、2
max_price：默认值：0
min_price：默认值：0
free_shipping：默认值：false
small_business：默认值：false

请求控制

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

附加约束

no_cache：默认值：false

引擎列表

Google Shopping 搜索