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; longer than 200 characters or 16 words is shortened
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	—	the largest edge of the product image in pixels: 40, 60, 80, 100, 150, 200, 250, 300, 400 or 500
filter[<field>][]	—	a facet filter; the field is a name from facets[].field, for example filter[Typ produktu][]=vŕtačka

Any other parameter is rejected with 422 invalid_parameter naming it, so a misspelled parameter never silently returns an unfiltered result.

Filters

category[]=Náradie > Vŕtačky&category[]=Náradie > Brúsky   → first OR second category
filter[farba][]=modrá&filter[farba][]=čierna               → blue OR black
filter[farba][]=modrá&filter[Max. vý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 — filter[farba][]=modrá&filter[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.

The field name goes inside filter[…] exactly as it appears in facets[].field, including spaces and dots — filter[Max. výkon][]=800 W. URL-encode the query string as usual. A field that is not among the facets of the catalog matches no product.

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. The product fields brand and price are not facets — filter[brand][]=Bosch therefore returns nothing unless you also send the brand in params. Price has its own price_min and price_max parameters.

The one exception is in_stock: we turn it into the facet dostupnost (label Dostupnosť) with the values Skladom and Nie je skladom. It is returned only when the result contains both values, and you filter by it like by any other facet — filter[dostupnost][]=Skladom.

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://search.api.metty.eu/media/product-thumbs/bf/51/bf51ceb732283ebbe985717ef0fe09a7b9bd909fb1b9e8692dd6aba5d63b1370-500.webp",
      "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 }]
}

• query is the query as we searched it: a q longer than 200 characters or 16 words comes back shortened.
• 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. image_size is a maximum, not an exact width: the image is scaled down to fit a box of that size, so a portrait picture ends up narrower and a source smaller than the requested size is served as it is — we never upscale it. Size the slot in CSS and do not expect the returned file to have exactly that width. Every size is served from the same URL with the number 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, code or category; brand is never highlighted. highlight.category is the full path like category, with the markers only in its last level (Náradie > [Vŕtačky]); a match in a parent category alone is not highlighted. The [] markers are produced by the server; on the client you only replace them with <mark> and compute nothing.
• advisor is present only for an e-shop with the advisor switched on in Metty, and only when it recognised something in the query: {"understood": [{"field": "Pre koho", "value": "Ženy"}], "excluded": 2}. understood lists the recognised field and value as display text; excluded is the number of products left out of the result as unsuitable. When excluded is above zero, total counts only the remaining products within the window of the first 200 results. The request does not change.

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 (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 values, the most frequent ones in the result; see the order below
range	optional {min, max, unit} for a field whose values are all numbers in one unit, for example to label a slider; filtering is still by values

The order of values is stable: by frequency in the result without facet filters, not by the current counts, so a click does not reshuffle the list. Numeric fields and classes (A–G) are ordered by value. A value that the active selection rules out stays in the list with count: 0 — show it as unavailable rather than hiding it.

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

With a category filter, categories is computed without it, like facets: it also returns other categories where the query (with the price filter) found products, so the customer can add them to the selection. A selected category with no products may be missing from the response.

categories needs category URLs

The section is built as a shortcut to the category pages of your e-shop, so a category we have no URL for is left out — with no URL at all the section comes back empty even though the catalog has categories. The URLs come from an XML feed import; the Catalog API carries the category path on the product and has no field for the URL of the category itself, so for a catalog written purely through it we have to fill the URLs in on our side.

This affects the categories section only. Filtering by category and the products[].category path work regardless, so a category page of your own can always be built from the path.

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. image_size and the shortening of q work the same as in GET /search.

{
  "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://search.api.metty.eu/media/product-thumbs/bf/51/bf51ceb732283ebbe985717ef0fe09a7b9bd909fb1b9e8692dd6aba5d63b1370-500.webp",
      "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.