Vyhľadávanie

Search API je určené pre integrátorov s vlastným UI. Beží nad rovnakým vyhľadávaním ako widget — rovnaký ranking, rovnaké návrhy.

https://search.api.metty.eu

Autentifikácia prebieha verejným kľúčom v query parametri: ?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	význam
key	—	povinný verejný kľúč <PUBLIC_API_KEY>
q	—	dotaz; prázdny q s filtrami vráti výpis katalógu
page	1	stránka, číslovaná od 1
per_page	24	veľkosť stránky, oreže sa na rozsah 1–100
category	—	cesta kategórie; pre ALEBO medzi cestami ju opakujte ako category[]
price_min, price_max	—	cenové rozpätie, nezáporné čísla
sort	relevance	relevance, price_asc, price_desc, name_asc
include	—	facets, categories, suggestions (oddelené čiarkou)
image_size	—	šírka obrázka produktu v pixeloch: 40, 60, 80, 100, 150, 200, 250, 300, 400 alebo 500
ostatné	—	facetové pole z vášho katalógu, napríklad farba=modrá

Filtre

category[]=Náradie > Vŕtačky&category[]=Náradie > Brúsky   → prvá ALEBO druhá kategória
farba[]=modrá&farba[]=čierna                               → modrá ALEBO čierna
farba=modrá&príkon=800 W                                   → modrá A ZÁROVEŇ 800 W
price_min=50&price_max=200                                 → cenové rozpätie

Opakovaná hodnota potrebuje []

Parameter, ktorý posielate viackrát, musí mať príponu [] — farba[]=modrá&farba[]=čierna. Bez nej prežije iba posledná hodnota a filter zúži výsledok viac, než ste zamýšľali. Jedna hodnota funguje so zátvorkami aj bez nich.

Cesta kategórie je vždy úplná cesta od koreňa s úrovňami oddelenými > — presne v tvare, v akom ju vraciame v products[].category a v categories[].path.

Facetom je iba to, čo je v params

Facetové polia vznikajú z params (Catalog API), respektíve z parametrov produktu vo feede. Názov parametra je priamo názov poľa. Vlastné polia produktu (brand, in_stock, price) facetmi nie sú — filter brand=Bosch preto nevráti nič, pokiaľ značku neposielate aj v params. Cena má vlastné parametre price_min a price_max.

V odpovedi sa môžu objaviť aj facety, ktoré ste nikdy neposlali: na požiadanie generujeme ďalšie parametre z textov produktov a po schválení ich indexujeme popri vašich. Jednotlivé facety sa dajú aj vypnúť pre konkrétnu kategóriu. Oboje sa nastavuje v Metty, nie cez API — zoznam použiteľných polí preto berte zo sekcie facets v odpovedi, nie z vlastného katalógu.

Multi-select: ak zafiltrujete jednu hodnotu poľa, ten istý facet naďalej vracia aj ostatné hodnoty aj s počtami, aby zákazník mohol prepnúť. Ostatné facety sa prepočítajú podľa aktívnych filtrov.

Stránkovanie

Súčin (page − 1) × per_page + per_page môže byť najviac 200. Za touto hranicou už výsledky nerankujeme, takže hlbšia stránka by vrátila neusporiadané poradie; požiadavka skončí chybou 422.

Explicitný sort má prednosť pred relevanciou — pri price_asc poradie nijako neupravujeme.

Odpoveď

{
  "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 je null, ak sa oprava preklepu neaplikovala.
• image je WebP, ktoré sme si uložili z vášho obrázka, a servírujeme ho zo search.api.metty.eu. Bez image_size ide o uložený 500 px variant; s ním vrátime presne vyžiadanú šírku. Každá šírka sa servíruje z tej istej URL s veľkosťou v názve, takže na poskladanie srcset stačí jedna odpoveď — prepíšete číslo a výber necháte na prehliadači. Produkt, ktorého obrázok sme ešte nestihli stiahnuť — čerstvý zápis cez Catalog API — má image: null, kým job na pozadí nedobehne.
• list_price je cena pred zľavou; pri produkte mimo akcie je null.
• categories, facets, price_range a suggestions sú v odpovedi iba vtedy, ak sú uvedené v include; price_range prichádza spolu s facets.
• highlight obsahuje iba polia so zhodou — name, description, brand, category alebo code. Značky [] generuje server; na klientovi ich stačí nahradiť za <mark> a nič nedopočítavať.

Facety a kategórie

facets je zoznam, nie mapa. Poradie je stabilné a každé pole nesie aj zobrazovaný názov:

pole	význam
field	názov poľa, ktorý posielate späť ako filter (farba=modrá)
label	zobrazovaná podoba; strojový názov z feedu prepisujeme na čitateľný (graficka_karta → Graficka karta)
values	najviac 20 najčastejších hodnôt, zoradených podľa počtu

categories vracia najviac 10 kategórií, suggestions najviac 8 návrhov.

Pri aktívnom facetovom filtri sa počty aj total vzťahujú na okno prvých 200 výsledkov — facety počítame až nad zoradeným výsledkom, aby zodpovedali tomu, čo zákazník uvidí.

Našepkávanie

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

Parameter limit sa oreže na rozsah 1–20 (default 8) a obmedzuje počet navrhovaných dotazov. Server ich zostaví najviac 8, takže hodnota nad 8 odpoveď nerozšíri. Návrhy sú totožné s tými, ktoré používa widget.

{
  "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"
    }
  ]
}

Pole products obsahuje najviac 5 položiek v skrátenom tvare, určenom pre dropdown pod vyhľadávacím poľom.

Hotová implementácia oboch endpointov je v príkladoch.