Guides
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 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.