search_shops

Searches or browses shops near the delivery location. Each result carries a shop_id and a cart_id: the cart_id encapsulates the shop and the delivery coordinates, and is the entry point for the subsequent get_shop_menu, quote_cart, and preview_order calls.

Order flow: search_shops → shop_id + cart_id (carries delivery coordinates) → get_shop_menu to pick items → quote_cart to price the cart and get quote_id → select_address to get address_id → preview_order → preview_id + confirmation_token → create_order. Pass the shop_id / cart_id to downstream tools as-is; do not synthesize them.

Two modes (switched by keyword):

Omit / empty keyword → browse mode: a nearby shop feed (up to 20) with decision fields — distance, rating, delivery fee, minimum order amount, and availability.
Provide keyword → precise search (~5 shops): keyword may be a shop name (“瑞幸咖啡”), a category (“奶茶”), or a concrete item name (“生椰拿铁”); the upstream search matches at the item level, so an item keyword returns the shops that actually carry it. Each shop includes matched_items (display-only previews of the matched items). Note: in this mode distance / rating are usually null (upstream limitation); but delivery_time_text / delivery_fee_text are now derived from the upstream orderLeadTime / floatDeliveryFee (a fee of 0 shows as “免配送费”, i.e. free delivery).

Browse pagination: in browse mode (no keyword), pass offset to page through results — send offset: 0 on the first call, then the response’s next_offset on each subsequent call, until shops comes back empty (end reached). Page size is fixed and not adjustable (it only caps how many shops one page may return). Keyword search does not support pagination.

A keyword search does not necessarily return the shop you asked for. The search never returns an empty list — when no shop name matches the keyword, it falls back to similar shops in the same category. search_match_level tells the two apart:

exact — at least one shop’s name or brand matches the keyword; those shops are listed first.
related — no shop name matched; every result is a same-category alternative. For a category keyword (“奶茶”) that is normal. For a shop or brand keyword (“星巴克”) it means that brand is not orderable at this delivery location — do not treat the results as the shop the user asked for. Tell the user it wasn’t found, or retry with a different address.

Parameters

Parameter	Type	Required	Default	Description
`consent_grant_id`	string	Yes	—	User consent grant ID (`cg_` prefix, from `verify_user_bind`), identifying the consenting user
`keyword`	string \| null	No	`null`	Keyword: shop name / category / item name. Omit or leave blank for browse mode
`address_id`	string \| null	No	`null`	Gateway address ID (from `select_address`); resolves the delivery location, takes priority over `lat`/`lng`
`lat`	float \| null	No	`null`	Latitude (GCJ-02)
`lng`	float \| null	No	`null`	Longitude (GCJ-02)
`city`	string \| null	No	`null`	City name to scope the search
`offset`	integer \| null	No	`null`	Browse mode only: pagination cursor. Omit = first page; pass the previous `next_offset` to fetch the next page. Page size is fixed and not adjustable. Ignored when `keyword` is set
`exclude_required_selection`	boolean	No	`false`	Drop shops where the user would have to pick a second time before checking out — either the shop has a required group (a hotpot base, say), or no single dish reaches the delivery minimum. Browse mode pages forward to refill the list; keyword mode does not page, so a category where every shop qualifies comes back empty
`with_recommendations`	boolean	No	`false`	Attach 1–2 signature dishes per shop (see `recommend_items`), each with its own `item_id`
`chain_brands_only`	boolean	No	`false`	Return only chain-brand shops, dropping independent one-off ones. This is “is it a chain”, not “is it good” — a well-regarded single-location restaurant is dropped too
`lang`	string	No	—	Language for this response. One of `zh` / `en` / `ja` / `ko` / `ru` / `ms` / `es`; defaults to the language set at binding time (Chinese if unset)
`include_chinese`	boolean	No	false	When `true`, the response also includes the Chinese original (`<key>_zh`) — see Bilingual responses

How the delivery location is resolved: in order, ① the coordinates of the saved address behind address_id → ② the lat/lng passed explicitly → ③ the user’s most-recently-used saved address / remembered location. If none resolve, the call returns COORDS_REQUIRED. So address_id and lat/lng are both optional, but at least one location source must be resolvable.

Returns

{
  "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": "Coconut Latte",
          "description": "Coconut milk + espresso",
          "price": 1600,
          "original_price": 2900,
          "image_url": "https://cube.elemecdn.com/…",
          "needs_spec_selection": true
        }
      ]
    }
  ],
  "search_match_level": "exact",
  "next_offset": 20
}

Amount fields are in cents (integer), not yuan. e.g. min_order_amount: 0 means ¥0, price: 1600 means ¥16.00.

Field	Type	Description
`shops`	array	Shop list (up to 20 in browse mode, ~5 in keyword search)
`search_match_level`	string	Keyword search only: `exact` = at least one shop name or brand matched the keyword, and those shops are listed first; `related` = no shop name matched, the results are same-category alternatives. Browse mode does not include this field
`next_offset`	integer \| null	Returned only when paging in browse mode (request included `offset`): cursor for the next page, use as the next request’s `offset`; empty `shops` means the end. Requests without `offset` do not include this field
`shops[].shop_id`	string	Shop ID (`shop_` prefix); pass to `get_shop_menu` / `quote_cart` / `preview_order` as-is
`shops[].cart_id`	string	Cart context ID (`cart_` prefix), carries the shop & delivery coordinates; downstream tools reuse it instead of passing lat/lng
`shops[].name`	string	Shop name
`shops[].brand_name`	string \| null	Brand name
`shops[].tags`	string[]	Category tags: one of `咖啡` / `奶茶` / `快餐`, or empty `[]` when none. For client-side category filtering; the gateway does not filter for you
`shops[].logo_url`	string \| null	Shop logo URL
`shops[].distance_text`	string \| null	Distance from the delivery location (text; may be `null` in keyword search mode)
`shops[].delivery_time_text`	string \| null	Estimated delivery text; present in both modes, `null` only when the upstream omits it
`shops[].delivery_fee_text`	string \| null	Delivery fee text; present in both modes, `null` only when the upstream omits it; a fee of 0 shows as “免配送费” (free delivery)
`shops[].rating`	float \| null	Rating (may be `null` in keyword search mode)
`shops[].monthly_sales_text`	string \| null	Monthly sales text. Currently always `null` — shop-level monthly sales are not available; for per-dish monthly sales see `items[].tip_texts` on `get_shop_menu`
`shops[].min_order_amount`	integer \| null	Minimum order amount (cents); `null` when absent
`shops[].available`	boolean	Whether orderable (open and not closed)
`shops[].unavailable_reason`	string \| null	Reason if unavailable
`shops[].matched_items`	array	Matched item previews (keyword search only; display-only)
`shops[].matched_items[].name`	string	Item name
`shops[].matched_items[].description`	string \| null	Item description (max 80 chars)
`shops[].matched_items[].price`	integer	Item price (cents)
`shops[].matched_items[].original_price`	integer \| null	Original price (cents)
`shops[].matched_items[].image_url`	string \| null	Item image URL (upstream thumbnail, ~184×184). For the original or another size, rewrite/drop the trailing `?x-oss-process` parameter
`shops[].recommend_items`	array	1–2 signature dishes for the shop (only when `with_recommendations: true`). Picked by monthly sales and the shop’s own hot/signature categories, with sub-¥1 loss leaders excluded
`shops[].recommend_items[].item_id`	string	Item ID. Pair it with this shop’s `cart_id` to call `get_item_options` right away and see specs and add-ons, with no full menu pull; pricing and ordering start with one `get_shop_menu` call, and the ID stays valid across it
`shops[].recommend_items[].name`	string	Item name
`shops[].recommend_items[].description`	string \| null	Item description (up to 80 chars)
`shops[].recommend_items[].price`	integer	Price in cents. This is the cheapest variant’s price — confirm the real one with `quote_cart`
`shops[].recommend_items[].original_price`	integer \| null	Original price in cents
`shops[].recommend_items[].image_url`	string \| null	Image URL, same as `matched_items`
`shops[].recommend_items[].needs_spec_selection`	boolean	Whether the dish has several size/spec variants. `true` means you must pick one via `get_item_options` before ordering; `false` only means no size choice showed up — required add-on groups may still apply, and `get_item_options` is authoritative

matched_items carry no IDs and no stock state — to order one of those, call get_shop_menu first and use the item_id / sku_id / option IDs it returns.recommend_items do carry an item_id: pair it with the shop’s cart_id and call get_item_options right away. Pricing and ordering still start with one get_shop_menu call on that cart, and the same item_id stays valid across it.

Error Codes

code	Description
`CONSENT_GRANT_REQUIRED`	Missing `consent_grant` (no consent grant passed)
`CONSENT_GRANT_INVALID`	Consent grant is invalid
`CONSENT_GRANT_EXPIRED`	Consent grant has expired; re-authorization required
`CAP_NOT_BOUND`	This capability is not enabled for the Agent
`CONSENT_GRANT_WRONG_CAP`	Consent grant belongs to a different capability or provider
`PUBLIC_REFERENCE_INVALID`	`address_id` is invalid or does not belong to the consented user
`COORDS_REQUIRED`	Neither `address_id` nor `lat`/`lng` was given and no remembered location is available
`ELEME_ERROR`	Upstream search API error

See Error Handling for the full list.

Example Call

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

Overview

Integration

Guides

Authorization

Shops

Addresses

Order

Payment

search_shops

search_shops

Parameters

Returns

Error Codes

Example Call

​search_shops

​Parameters

​Returns

​Error Codes

​Example Call

search_shops

Parameters

Returns

Error Codes

Example Call