Developers

Search API

One call turns what a shopper types, in English or Thai, into a page of Villa Market products: the best match first, then sections, with stock and promotions. This page is for Villa's web team, to put it into villamarket.com.

Quick start

Send the search as typed. Ask for the simple view: the storefront's own cards and sections.

const res = await fetch("SEARCH_API_BASE/api/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ q: "turkey", view: "simple" }),
});
if (!res.ok) throw new Error(`search: ${res.status}`);
const result = await res.json();
console.log(result.page[0].name); // "Oven Roasted Turkey"

curl -s SEARCH_API_BASE/api/search \
  -H 'Content-Type: application/json' \
  -d '{"q":"turkey","view":"simple"}'

The answer (a real one, trimmed to two products):

{
  "query": "turkey",
  "engine": "rerank",
  "page": [
    {
      "cprcode": "257624",
      "name": "Oven Roasted Turkey",
      "name_th": "เนื้อไก่งวงบดอัดก้อนปรุงรส",
      "brand": "SPAM",
      "size": "340g",
      "price": 269,
      "list_price": 299,
      "promo": null,
      "stock": 74,
      "image": "https://d1vl5j0v241n75.cloudfront.net/0257624-1",
      "country": "US",
      "shelf": "Grocery › Cans & Packets › Meals & Meats",
      "group": "Cans & Packets › Meals & Meats",
      "tier": "STRONG",
      "band": 0
    },
    {
      "cprcode": "136873",
      "name": "Roasted Carved Turkey",
      "brand": "Hungry-Man",
      "size": "454g",
      "price": 310,
      "list_price": null,
      "promo": null,
      "stock": 9,
      "image": "https://d1vl5j0v241n75.cloudfront.net/0136873",
      "country": "US",
      "shelf": "Frozen Food › Ready Meals › Chicken",
      "group": "Ready Meals › Chicken",
      "tier": "STRONG",
      "band": 0
    }
  ],
  "groups": [
    {
      "key": "Cans & Packets › Meals & Meats",
      "count": 1
    },
    {
      "key": "Ready Meals › Chicken",
      "count": 1
    },
    {
      "key": "Pies & Sausage Rolls › Pies",
      "count": 2
    }
  ],
  "understood": {
    "kind": "product",
    "label": "turkey",
    "food": true,
    "country": null,
    "intent": [],
    "alternative": {
      "kind": "origin",
      "q": "products from turkey",
      "country_en": "Turkey",
      "country_th": "ตุรกี"
    },
    "did_you_mean": null,
    "suggestions": [
      "products from turkey",
      "Breadcrumbs & Stuffing"
    ]
  },
  "jev": {
    "requests": 2,
    "cached": 2,
    "input_tokens": 7863,
    "live_requests": 0,
    "live_input_tokens": 0,
    "limit": null
  },
  "timing": {
    "total_ms": 51
  }
}

Show page in the order it comes, in the sections of groups, under the line understood describes. The integration guide covers each part, or the widget renders it all in one line.

POST /api/search

A search. The body is JSON, 20 KB at most. Only q is required.

There is no lang field: every product comes with its English and Thai names, and the page picks. Filters (in stock, on promotion) are the page's too, over the products returned.

The response

A product card

Other fields (reading, pipeline, counts, context_sent and more) are the demo's diagnostics. They are not part of the contract and may change.

GET /api/meta

The service's settings, for a status line or a health check.

Errors

Errors are JSON: { "error": "…" }, a sentence safe to log (never to show as it is: show your own words).

Pricing and limits

A search costs what the model reads for it, plus a small share of the servers. Nothing runs between searches: there is no search cluster or cache server to pay for.

cost of a search ≈ live model input tokens × $0.042 / 1,000,000 + $0.00003 (AWS)

• Repeats cost no model calls for 30 days. The model's answers are kept, so a popular search pays the model once a month; each repeat still costs the servers' share, ≈ 0.003¢. The table counts every search as new, so the real average is lower.
• Some answers need no model calls at all: the quick phase, and the shop's own order when a limit is reached (with a notice).
• Every search is capped: a simple search stops asking the model at 3 requests or 20,000 tokens (about 0.09¢), whichever comes first.
• Prices: the model input price ($42 per billion input tokens; no output price is listed); AWS at public prices, approximate. /api/meta carries them as cost, with jev_tokens_today.

Limits

The model is asked only when an answer is not already known. The limits below count only live model requests.

A request with an API key has its client's own rate and daily model tokens instead of the visitor's: see access.

Guide

Integrate villamarket.com

Where to call it

• The search results page first. Call it when a shopper submits a search, from the page or from your server (with an API key).
• Type-ahead later. The quick phase answers in milliseconds with no model calls, and suits suggestions as the shopper types; the full search runs when they submit.
• Keep the storefront's own search as the fallback. On a 429, a 5xx or a timeout (5 seconds is plenty), show today's search, never an empty page.

Render the page

1. The understood line. understood.label, with the count in stock. If there is did_you_mean or an alternative, one link each: a click is a new search.
2. Filters. Chips over the products returned: in stock, on promotion (promo or list_price), local (country TH). Hide a chip that would not change the page.
3. The best match. One larger card: the first in-stock card of the best band among the first three. Never an out-of-stock card or a substitute.
4. Sections. Group page by group, in the order of groups. A section of one product can join a "Top matches" row. Keep the page's order inside each.
5. Each card. Photo, name, brand and size, price; a struck-through list_price with a promotion; "Out of stock" greyed but readable.
6. A notice. When notice is present, one quiet line: "Showing the shop's usual results."

This is the demo's Simple view. The widget is that view in one element, and its script (villa-search.js, not minified) is the reference: layout() makes the sections, renderSmart() the page.

English and Thai

A shopper can search in either language on either page. Show name_th on a Thai page when it is there, else name. Section names are Villa's English category names: translate them with group_th first, then your own category table.

Caching

Answers carry Cache-Control: no-store, because stock and the day's budget change. A server may keep an answer a minute per search. Repeats are cheap anyway: the service keeps the model's answers for 30 days.

Analytics worth sending

Guide

The <villa-search> widget

The whole results page in one element: the understood line, filters, the best match and sections, in English or Thai, on a phone or a desktop. It is the demo's Simple view, in a shadow root, so your CSS and its CSS never meet.

<script src="SEARCH_API_BASE/villa-search.js" defer></script>
<villa-search q="turkey" lang="th"></villa-search>

It calls the API from the shopper's browser, so the page's site must be on the CORS list. It never takes an API key.

Attributes

Events

const results = document.querySelector("villa-search");
results.addEventListener("villa-search:select", (e) => {
  e.preventDefault();
  router.push(`/product/${e.detail.cprcode}`);
});
searchBox.addEventListener("submit", (e) => {
  e.preventDefault();
  results.search(searchBox.q.value);
});

Style it

Set these on the element or any parent. Each has the demo's colour as its default.

villa-search {
  --vs-font: "Kanit", system-ui, sans-serif;
  --vs-accent: #0b6e4f;
  --vs-promo: #ffcc00;
  --vs-radius: 8px;
}

Production

Access and API keys

From a browser: Villa's sites

Pages on these sites may call the API directly. The browser sends its Origin, and the API answers with Access-Control-Allow-Origin for these only:

• https://shop.villamarket.com
• https://dev.villamarket.net
• https://villamarket.com
• https://www.villamarket.com

Each shopper counts as a visitor for the limits. Another site, a new test host for instance, is a setting: ask for it.

From a server: an API key

A server that calls on behalf of many shoppers sends a key, and gets its own rate and daily model tokens instead of one visitor's. The site's daily model budget still applies to everyone.

curl -s SEARCH_API_BASE/api/search \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $VILLA_SEARCH_API_KEY" \
  -d '{"q":"turkey","view":"simple"}'

• Keys are issued by hand, one per client, with its searches a minute and model tokens a day. Ask the team that runs this service.
• A key lives on your server: in its secret store, never in a web page, a repository or a chat. Only a hash of it is kept here.
• An unknown or revoked key gets 401. A key that leaks is revoked, and a new one issued.