search_shops

按配送位置搜索或浏览店铺。每个结果都附带 shop_id 与 cart_id：cart_id 已封装该店铺与本次配送坐标，是后续 get_shop_menu、quote_cart、preview_order 的入口。

下单链路：search_shops 得 shop_id + cart_id（已含配送坐标）→ get_shop_menu 选商品 → quote_cart 算价得 quote_id → select_address 得 address_id → preview_order 得 preview_id + confirmation_token → create_order。下游工具的 shop_id / cart_id 必须原样回传，不要自造。

两种模式（由 keyword 切换）：

不传 / 传空 keyword → 浏览模式：返回附近店铺信息流（最多 20 家），带距离、评分、配送费、起送价、营业状态等决策字段。
传 keyword → 精确搜索（约 5 家）：keyword 可为店名（“瑞幸咖啡”）、品类（“奶茶”）或具体商品名（“生椰拿铁”）；上游按商品级匹配，故商品名关键词会返回真正在售该商品的店铺。每家店附带 matched_items（仅展示用的命中商品预览）。注意：此模式下 distance / rating 通常为 null（上游限制）；而 delivery_time_text / delivery_fee_text 现可由上游 orderLeadTime / floatDeliveryFee 带出（配送费为 0 时显示「免配送费」）。

浏览翻页：浏览模式（不传 keyword）下传 offset 翻页——首次传 offset: 0，返回会带 next_offset，下次把它作为 offset 继续翻，直到返回 shops 为空即到底。每页数量固定、不可调（仅作每页查询量上限）。关键词搜索不支持翻页。

关键词搜索给回来的，不一定是你要的那家店。 搜索从不返回空列表——当没有任何店名对上关键词时，它会改推同品类的相似店铺。search_match_level 就是用来区分这两种情况的：

exact — 至少有一家店的店名或品牌名对上了关键词，这些店排在列表最前面。
related — 没有一家店名对得上，返回的全是同品类的相似店。用品类词搜（“奶茶”）时这很正常；但用店名或品牌搜（“星巴克”）时，它意味着该品牌在这个配送位置点不到，返回的只是同类替代——别把它们当成用户要的那家店，先告诉用户没搜到，或换个地址再试。

参数

参数	类型	必填	默认	说明
`consent_grant_id`	string	是	—	用户授权 ID（`cg_` 前缀，来自 `verify_user_bind`），标识已授权用户
`keyword`	string \| null	否	`null`	关键词：店名 / 品类 / 商品名。不传或传空则进入浏览模式
`address_id`	string \| null	否	`null`	网关地址 ID（来自 `select_address`）；用于解析配送坐标，优先于 `lat`/`lng`
`lat`	float \| null	否	`null`	纬度（GCJ-02）
`lng`	float \| null	否	`null`	经度（GCJ-02）
`city`	string \| null	否	`null`	城市名，用于限定搜索范围
`offset`	integer \| null	否	`null`	仅浏览模式：翻页游标。不传=第一页；传上次返回的 `next_offset` 取下一页。每页数量固定、不可调。带 `keyword` 时忽略
`exclude_required_selection`	boolean	否	`false`	不返回「下单前还要再选一样东西」的店。两种情形都算：店里有必选组（如麻辣烫的必选汤底），或全店没有一件单点够起送价。浏览模式下会自动往后翻页把结果补够；关键词模式不翻页，整个品类都不合格时会返回空列表
`with_recommendations`	boolean	否	`false`	每家店带 1~2 个招牌菜（见 `recommend_items`），各自带 `item_id`
`chain_brands_only`	boolean	否	`false`	只返回连锁品牌店，过滤掉单店。这是「是不是连锁」，不是「好不好」——口碑很好的独立单店也会被一起过滤掉
`lang`	string	否	—	本次返回内容使用的语言，枚举 `zh` / `en` / `ja` / `ko` / `ru` / `ms` / `es`；不传则用绑定时设定的语言（默认中文）
`include_chinese`	boolean	否	false	为 `true` 时响应同时返回中文原文（`<key>_zh`），见双语响应

配送坐标如何解析：依次取 ① address_id 对应保存地址的经纬度 → ② 显式传入的 lat/lng → ③ 该用户最近使用过的保存地址 / 历史定位。三者都没有时返回 COORDS_REQUIRED。即 address_id 与 lat/lng 均为可选，但至少要能解析出一个位置。

{
  "shops": [
    {
      "shop_id": "shop_4f2a...",
      "cart_id": "cart_9b3e...",
      "name": "瑞幸咖啡(人民广场店)",
      "brand_name": "瑞幸咖啡",
      "tags": ["咖啡"],
      "logo_url": "https://image.url/shop.jpg",
      "distance_text": "1.2km",
      "delivery_time_text": "35分钟",
      "delivery_fee_text": "配送 ¥3",
      "rating": 4.8,
      "monthly_sales_text": null,
      "min_order_amount": 0,
      "available": true,
      "unavailable_reason": null,
      "matched_items": [
        {
          "name": "生椰拿铁",
          "description": "椰浆+浓缩咖啡",
          "price": 1600,
          "original_price": 2900,
          "image_url": "https://cube.elemecdn.com/8/be/57a834efd750f506fb634dd3f6700jpg.jpg?x-oss-process=image/resize,m_fill,w_184,h_184/quality,q_75"
        }
      ],
      "recommend_items": [
        {
          "item_id": "item_86392cde7a77b08d80e09c08da88620e",
          "name": "生椰拿铁",
          "description": "椰浆+浓缩咖啡",
          "price": 1600,
          "original_price": 2900,
          "image_url": "https://cube.elemecdn.com/…",
          "needs_spec_selection": true
        }
      ]
    }
  ],
  "search_match_level": "exact",
  "next_offset": 20
}

金额字段单位为分（整数），不是元。例如 min_order_amount: 0 表示 ¥0、price: 1600 表示 ¥16.00。

字段	类型	说明
`shops`	array	店铺列表（浏览模式最多 20 家，关键词搜索约 5 家）
`search_match_level`	string	仅关键词搜索返回：`exact`=至少一家店名或品牌名对上了关键词，这些店排在最前；`related`=没有店名对得上，返回的是同品类相似店。浏览模式不含此字段
`next_offset`	integer \| null	仅浏览翻页时返回（请求带了 `offset`）：下一页游标，作为下次请求的 `offset`；`shops` 为空即到底。不传 `offset` 的请求不含此字段
`shops[].shop_id`	string	店铺 ID（`shop_` 前缀）；原样传给 `get_shop_menu` / `quote_cart` / `preview_order`
`shops[].cart_id`	string	购物车上下文 ID（`cart_` 前缀），已封装该店铺与配送坐标；后续工具据此免传经纬度
`shops[].name`	string	店铺名称
`shops[].brand_name`	string \| null	品牌名
`shops[].tags`	string[]	品类标签：`咖啡` / `奶茶` / `快餐` 之一；命不中为空数组 `[]`。供调用方按品类筛选展示，平台不替客户过滤
`shops[].logo_url`	string \| null	店铺图标 URL
`shops[].distance_text`	string \| null	距配送位置距离（文案；关键词搜索模式可能为 `null`）
`shops[].delivery_time_text`	string \| null	预计送达文案；两种模式都带，仅上游未返回时为 `null`
`shops[].delivery_fee_text`	string \| null	配送费文案；两种模式都带，仅上游未返回时为 `null`；配送费为 0 显示「免配送费」
`shops[].rating`	float \| null	评分（关键词搜索模式可能为 `null`）
`shops[].monthly_sales_text`	string \| null	月销文案。当前恒为 `null`，店铺维度的月销暂不提供；商品维度的月售见 `get_shop_menu` 的 `items[].tip_texts`
`shops[].min_order_amount`	integer \| null	起送金额（分）；缺失为 `null`
`shops[].available`	boolean	是否可下单（营业且未关闭）
`shops[].unavailable_reason`	string \| null	不可用原因
`shops[].matched_items`	array	命中商品预览（仅关键词搜索有；仅展示用）
`shops[].matched_items[].name`	string	商品名
`shops[].matched_items[].description`	string \| null	商品描述（最多 80 字）
`shops[].matched_items[].price`	integer	商品价（分）
`shops[].matched_items[].original_price`	integer \| null	原价（分）
`shops[].matched_items[].image_url`	string \| null	商品图 URL（上游缩略图，约 184×184）。如需原图或其它尺寸，改写/删除末尾 `?x-oss-process` 参数
`shops[].recommend_items`	array	该店 1~2 个招牌菜（仅 `with_recommendations: true` 时返回）。按月售与商家标注的热销 / 招牌分类挑选，并排除 1 元以下的引流商品
`shops[].recommend_items[].item_id`	string	商品 ID。配本店的 `cart_id` 可直接调 `get_item_options` 查规格与配料，不必先拉整本菜单；要算价或下单，先调一次 `get_shop_menu`，这个 ID 在那之后仍然有效
`shops[].recommend_items[].name`	string	商品名
`shops[].recommend_items[].description`	string \| null	商品描述（最多 80 字）
`shops[].recommend_items[].price`	integer	商品价（分）。这是该商品最低规格档的价格，实际金额以 `quote_cart` 为准
`shops[].recommend_items[].original_price`	integer \| null	原价（分）
`shops[].recommend_items[].image_url`	string \| null	商品图 URL，同 `matched_items`
`shops[].recommend_items[].needs_spec_selection`	boolean	是否有多个规格档（如大杯 / 中杯）。`true` 时必须先用 `get_item_options` 选一档再下单；`false` 表示没有规格档可选，但仍可能有必选的加料组，以 `get_item_options` 为准

matched_items 不带 ID，也不含库存状态，要点其中的商品必须先调 get_shop_menu，用它返回的 item_id / sku_id / 选项 ID。recommend_items 带 item_id：配同店的 cart_id 可以直接调 get_item_options 查规格与配料。要算价或下单，仍要先调一次 get_shop_menu，这个 ID 在那之后仍然有效。

错误码

code	说明
`CONSENT_GRANT_REQUIRED`	缺少 `consent_grant`（未传用户授权）
`CONSENT_GRANT_INVALID`	用户授权无效
`CONSENT_GRANT_EXPIRED`	用户授权已过期，需重新授权
`CAP_NOT_BOUND`	该 Agent 未开通对应能力
`CONSENT_GRANT_WRONG_CAP`	授权属于其它能力或服务商
`PUBLIC_REFERENCE_INVALID`	`address_id` 无效或不属于当前授权用户
`COORDS_REQUIRED`	既未传 `address_id` 也未传 `lat`/`lng`，且无历史定位可回退
`ELEME_ERROR`	上游搜索接口异常

完整错误码见错误处理。

调用示例

{
  "name": "search_shops",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "keyword": "生椰拿铁",
    "address_id": "<来自 select_address>"
  }
}

概览

接入

指南

授权

店铺

地址

下单

支付

search_shops

search_shops

参数

返回

错误码

调用示例

​search_shops

​参数

​返回

​错误码

​调用示例

search_shops

参数

返回

错误码

调用示例