> Documentation index: https://www.xekta.com/llms.txt

# Search and results

> How to find shops and items, how to show them, and what the result modes mean.

## A location is optional for browsing

To answer a question such as "which markets are in San Francisco?", a city or neighborhood is enough: pass it as `near.place`. With no location at all, search still answers; results are then not sorted by distance. Never invent a location the buyer did not give.

Ask for a precise location (street address, cross streets or ZIP code) only before building a cart.

## Result modes

| `mode` | Meaning | What to do |
| - | - | - |
| `shops` | Two or more shops match. `next_step` is `buyer_chooses_shop`. | Show the shops (name, prep time, starting price) and ask which one. Do not build a cart yet. Then search again with `shop_id`. |
| `shop_dishes` | One shop matches. | Show its dishes directly. Do not ask which shop. |

For a shopping list, [`cart_build`](https://www.xekta.com/docs/tools/cart-build.md) returns `mode: "shops"` in the same way, with how many of the items each shop has and what is missing. Shops that have everything come first. When no shop has everything, say so plainly.

## Show picture cards

Results are built as a picture menu. Show them as cards with photo, name and price by default, without waiting for the buyer to ask for pictures.

| `image_source` | What it is | Rule |
| - | - | - |
| `shop` | The shop's own photo. | Show it as the shop's. |
| `stock` | A XEKTA stock photo of the dish. | Always show its `image_note` next to it. Never present it as the shop's picture. |

Never add photos from the web or anywhere else.

## A whole menu in one call

Search for the shop name and the word menu, such as `"Borek-G menu"`. The answer is the full menu, ready-to-eat items first, 60 items per page. `menu_page` and `menu_pages` say where you are, and `page: 2` returns the next 60.

## Stock

| `availability` | Meaning |
| - | - |
| `in_stock` | Available. |
| `low_stock` | Available, few left. |
| `out_of_stock` | Not available now. |
| `unknown` | The shop does not report stock for this item. It does not mean the item is missing. |

A photo says nothing about stock.

## Opening hours

Shops that are open now rank first. Offers from a shop outside its posted hours are still returned, with `shop_open_now: false` and `shop_opens_at`. An order to such a shop goes through only once it opens.

## When the buyer wants something to eat

For dinner, lunch or "I'm hungry", suggest ready-to-eat food only. Suggest packaged or frozen products only if the buyer asks for them.

## When nothing matches

Search again with a broader word, or an English word, and offer the closest items as alternatives. Add only items, options and notes the buyer picked.