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; dlhší než 200 znakov alebo 16 slov skrátime
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	—	najdlhšia hrana obrázka produktu v pixeloch: 40, 60, 80, 100, 150, 200, 250, 300, 400 alebo 500
filter[<pole>][]	—	facetový filter; pole je názov z facets[].field, napríklad filter[Typ produktu][]=vŕtačka

Každý iný parameter odmietneme chybou 422 invalid_parameter, ktorá ho menuje, takže preklep v názve parametra nikdy ticho nevráti nefiltrovaný výsledok.

Filtre

category[]=Náradie > Vŕtačky&category[]=Náradie > Brúsky   → prvá ALEBO druhá kategória
filter[farba][]=modrá&filter[farba][]=čierna               → modrá ALEBO čierna
filter[farba][]=modrá&filter[Max. vý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 [] — filter[farba][]=modrá&filter[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.

Názov poľa patrí do filter[…] presne v tvare, v akom je vo facets[].field, vrátane medzier a bodiek — filter[Max. výkon][]=800 W. Query string zakódujte do URL ako zvyčajne. Pole, ktoré medzi facetmi katalógu nie je, nevyhovuje žiadnemu produktu.

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. Polia produktu brand a 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.

Jedinou výnimkou je in_stock: robíme z neho facet dostupnost (label Dostupnosť) s hodnotami Skladom a Nie je skladom. Vrátime ho iba vtedy, keď výsledok obsahuje obe hodnoty, a filtruje sa ako ktorýkoľvek iný facet — filter[dostupnost][]=Skladom.

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://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 je dotaz tak, ako sme ho hľadali: q dlhší než 200 znakov alebo 16 slov sa vráti skrátený.
• 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. image_size je maximum, nie presná šírka: obrázok zmenšujeme tak, aby sa zmestil do štvorca danej veľkosti, takže výškový obrázok vyjde užší a zdroj menší než vyžiadaná veľkosť dostanete taký, aký je — nikdy ho nezväčšujeme. Miesto pre obrázok si preto vymedzte v CSS a nerátajte s tým, že vrátený súbor má presne tú šírku. Každá veľkosť sa servíruje z tej istej URL s číslom 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, code alebo category; brand nezvýrazňujeme nikdy. highlight.category je celá cesta ako category, so značkami iba v poslednej úrovni (Náradie > [Vŕtačky]); zhoda iba v nadradenej kategórii sa nezvýrazní. Značky [] generuje server; na klientovi ich stačí nahradiť za <mark> a nič nedopočítavať.
• advisor je v odpovedi iba pri e-shope so zapnutým Poradcom v Metty a iba vtedy, keď v dotaze niečo rozpoznal: {"understood": [{"field": "Pre koho", "value": "Ženy"}], "excluded": 2}. understood vymenúva rozpoznané pole a hodnotu ako zobrazovaný text; excluded je počet produktov, ktoré z výsledku vypadli ako nevhodné. Keď je excluded väčší než nula, total počíta iba zostávajúce produkty v okne prvých 200 výsledkov. Požiadavka sa nemení.

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 (filter[farba][]=modrá)
label	zobrazovaná podoba; strojový názov z feedu prepisujeme na čitateľný (graficka_karta → Graficka karta)
values	najviac 20 hodnôt, tých najčastejších vo výsledku; poradie je opísané nižšie
range	voliteľný objekt {min, max, unit} pre pole, ktorého hodnoty sú všetky čísla v jednej jednotke, napríklad na popis slidera; filtruje sa stále cez values

Poradie values je stabilné: podľa početnosti vo výsledku bez facetových filtrov, nie podľa aktuálnych počtov, takže sa po kliknutí zoznam nepremieša. Číselné polia a triedy (A–G) sú zoradené podľa hodnoty. Hodnota, ktorú aktívny výber vylučuje, ostáva v zozname s count: 0 — zobrazte ju ako nedostupnú, neskrývajte ju.

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

Pri filtri category sa categories počítajú bez neho, rovnako ako facety: vrátia aj ďalšie kategórie, v ktorých dotaz (s cenou) našiel produkty, takže ich zákazník môže pridať k výberu. Zvolená kategória bez produktov v odpovedi chýbať môže.

categories potrebuje URL kategórií

Sekcia je skratkou na kategórie vášho e-shopu, takže kategóriu, ku ktorej nemáme URL, vynechávame — bez URL sa vráti prázdna, aj keď katalóg kategórie má. URL prichádzajú z importu XML feedu; Catalog API nesie cestu kategórie na produkte a pole pre URL samotnej kategórie nemá, takže pri katalógu zapísanom výhradne cezeň ich musíme doplniť na našej strane.

Týka sa to iba sekcie categories. Filtrovanie cez category a cesta v products[].category fungujú aj bez toho, takže vlastnú stránku kategórie z cesty poskladáte vždy.

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. image_size a skracovanie q fungujú rovnako ako pri 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"
    }
  ]
}

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.