Search

The Search API is meant for integrators with their own UI. It runs on the same search stack as the widget — the same ranking, the same suggestions.

https://search.api.metty.eu

Authentication is the public key in a query parameter: ?key=<PUBLIC_API_KEY>.

GET /search

curl 'https://search.api.metty.eu/search?key=<PUBLIC_API_KEY>&q=vrtacka&per_page=24&include=facets,categories'

parameter	default	meaning
key	—	required public key <PUBLIC_API_KEY>
q	—	the query; an empty q with filters lists the catalog
page	1	page number, starting at 1
per_page	24	page size, clamped to 1–100
category	—	category path; repeat it as category[] to combine paths with OR
price_min, price_max	—	price range, non-negative numbers
sort	relevance	relevance, price_asc, price_desc, name_asc
include	—	facets, categories, suggestions (comma separated)
image_size	—	width of the product image in pixels: 40, 60, 80, 100, 150, 200, 250, 300, 400 or 500
anything else	—	a facet field from your catalog, for example farba=modrá

Filters

category[]=Náradie > Vŕtačky&category[]=Náradie > Brúsky   → first OR second category
farba[]=modrá&farba[]=čierna                               → blue OR black
farba=modrá&príkon=800 W                                   → blue AND 800 W
price_min=50&price_max=200                                 → price range

Repeated values need []

A parameter you send more than once must carry the [] suffix — farba[]=modrá&farba[]=čierna. Without it only the last value survives and the filter narrows the result more than you intended. A single value works with or without the brackets.

A category path is always the full path from the root with levels separated by > — exactly the format returned in products[].category and categories[].path.

Only params become facets

Facet fields come from params (Catalog API) or from product parameters in the feed. The parameter name is the field name. Product fields of their own (brand, in_stock, price) are not facets — a brand=Bosch filter therefore returns nothing unless you also send the brand in params. Price has its own price_min and price_max parameters.

The response may also contain facets you never sent: on request we generate additional parameters from product texts and, once approved, they are indexed alongside yours. Individual facets can also be switched off per category. Both are configured in Metty, not through the API — always take the list of usable fields from the facets section of the response rather than from your own catalog.

Multi-select: when you filter on one value of a field, that same facet keeps returning the remaining values with their counts so the customer can switch. Other facets are recalculated according to the active filters.

Paging

(page − 1) × per_page + per_page may be at most 200. Beyond that boundary results are no longer ranked, so a deeper page would return an unordered list; the request fails with 422.

An explicit sort takes precedence over relevance — with price_asc we do not reorder anything.

Response

{
  "query": "vrtacka",
  "corrected_query": "vŕtačka",
  "total": 132,
  "page": 1,
  "per_page": 24,
  "pages": 6,
  "products": [
    {
      "id": "sku-1",
      "name": "Príklepová vŕtačka Bosch",
      "url": "https://eshop.sk/vrtacka",
      "image": "https://eshop.sk/media/vrtacka.jpg",
      "price": 129.9,
      "list_price": 159.9,
      "currency": "EUR",
      "in_stock": true,
      "brand": "Bosch",
      "category": "Náradie > Vŕtačky",
      "highlight": { "name": "Príklepová [vŕtačka] Bosch" }
    }
  ],
  "categories": [{ "name": "Vŕtačky", "path": "Náradie > Vŕtačky", "count": 41 }],
  "facets": [
    {
      "field": "farba",
      "label": "Farba",
      "values": [{ "value": "modrá", "count": 12 }]
    }
  ],
  "price_range": { "min": 9.9, "max": 899 },
  "suggestions": [{ "query": "vŕtačka bosch", "count": 12 }]
}

• corrected_query is null when no typo correction was applied.
• image is the WebP we cached from your image, served from search.api.metty.eu. Without image_size it is the stored 500 px variant; with it we return exactly the width you asked for. Every width is served from the same URL with the size in its name, so a single response is enough to build a srcset — rewrite the number and let the browser pick. A product whose image has not been fetched yet — a fresh write through the Catalog API — has image: null until the background job finishes.
• list_price is the price before a discount; it is null for a product that is not on sale.
• categories, facets, price_range and suggestions are present only when listed in include; price_range comes together with facets.
• highlight contains only the fields that matched — name, description, brand, category or code. The [] markers are produced by the server; on the client you only replace them with <mark> and compute nothing.

Facets and categories

facets is a list, not a map. The order is stable and every field also carries a display name:

field	meaning
field	the field name you send back as a filter (farba=modrá)
label	the display form; a machine name from the feed is rewritten to something readable (graficka_karta → Graficka karta)
values	at most 20 most frequent values, ordered by count

categories returns at most 10 categories, suggestions at most 8 suggestions.

With an active facet filter, both the counts and total apply to the window of the first 200 results — facets are computed over the ranked result so that they match what the customer sees.

Autocomplete

curl 'https://search.api.metty.eu/suggest?key=<PUBLIC_API_KEY>&q=vrt&limit=8'

The limit parameter is clamped to 1–20 (default 8) and caps the number of query suggestions. The server builds at most 8 of them, so a value above 8 does not widen the response. The suggestions are the same ones the widget uses.

{
  "suggestions": [{ "query": "vŕtačka", "count": 41 }],
  "products": [
    {
      "id": "sku-1",
      "name": "Príklepová vŕtačka Bosch",
      "url": "https://eshop.sk/vrtacka",
      "image": "https://eshop.sk/media/vrtacka.jpg",
      "price": 129.9,
      "currency": "EUR"
    }
  ]
}

products holds at most 5 items in a compact form, meant for the dropdown under the search input.

A working implementation of both endpoints is in the examples.