Search API

General

epoq Search is an intelligent search. The search results are calculated in milliseconds and an intelligent algorithm outputs targeted results, for example by detecting and correcting errors, making suggestions and recognising automatic and manual adjustments.

For the setup of the intelligent search we need your product catalog in XML or CSV format. We hand over the tracking code for the connection to our knowledge base, which you integrate into your online shop.
You will receive a code snippet as a placeholder for the frontend of the intelligent search function, which you integrate into your online shop.
We create the search widget according to your requirements and it takes over the display of filters and search results.
We check the search field and filter functions, test weighting, ranking and error tolerance and optimise these settings.
The intelligent search is checked in detail in the test system and will be activated in the online shop after your approval.

By default, the currently popular browsers are supported.

Technical Integration

For API integration, you will find all the necessary information on this page to integrate epoq Search into your online shop.

Most important call parameters

The parameters mentioned here are needed for each call to get an authentication of your online shop. The parameters customerId and sessionId can be in many different formats on the online shop page and may need to be converted into a unique string representation for epoq search calls.

Parameter	Description
`tenantId`	The unique identification of your online shop. (Will be assigned to you by us)
`customerId`	A unique customer number of the shop visitor. Can be passed as soon as it is known. If unknown, leave empty.
`sessionId`	A unique identification of a customer’s session in the online shop.

Functions

epoq Search has an auto-suggest function (typeahead) for displaying search and product suggestions under the search box.

There is also an error-tolerant search function for displaying a search results page including product return, filter and sorting options, “Did you mean?” and paging.

These two services can be integrated into your shop either as individual parts or in combination.

Below you will find an https call and an example for the different functions. The required parameters are explained in detail below.

Auto-Suggest / Typeahead (search box)

The customer has entered a search text or part of a search text. The typeahead function enables an immediate display of possible terms that the customer could search/mine and offers them to the customer for selection.

The text suggestions can be linked to matching products, which can be displayed there.

Thus a return of suggestions / proposals takes place.

Typeahead Search

https://search.epoq.de/inbound-servletapi/getSearchResult

?tenantId=YOUR_epoq_IDENTIFICATION&sessionId=SESSION_ID&customerId=CUSTOMER_IDENTIFICATION&query=hood

Example display typeahead in the shop

Error-tolerant search (search results page)

The customer has entered and confirmed a search term or selected a proposal.

The search returns matching articles and the corresponding filters.

Full Search

https://search.epoq.de/inbound-servletapi/getSearchResult

?tenantId=YOUR_epoq_IDENTIFICATION&sessionId=SESSION_ID&customerId=CUSTOMER_IDENTIFICATION&query=hoodie&full&nrf

Filter / Sorting / Paging

For all search types there is the possibility to specify filter, sorting and a corresponding return size and offset (for following pages).

With filters the result set is limited to the desired value of a field.

The return is again a list of items.

Example for:

Filtering on category “Hoodies”, price between 50 and 100, sorted by price, return of 30 products (limit) from the 60th digit (corresponds to page 3)

Filter

https://search.epoq.de/inbound-servletapi/getSearchResult

?tenantId=YOUR_epoq_IDENTIFICATION&sessionId=SESSION_ID&customerId=CUSTOMER_IDENTIFICATION&ff=g:product_type&fv=Hoodies&ff=g:price&fv=>50&ff=g:price&fv=<100&orderBy=g:price&order=desc&limit=30&offset=60&full&nrf

Search Click Feedback

If a product from a search result is clicked on, a tracking request should be sent in order to enable later click and, if necessary, sales evaluation. For this purpose, the product ID of the clicked product should be transmitted, as well as the qid of the previous search request.

Click request

https://search.epoq.de/inbound-servletapi/clickSearchItem?

tenantId=YOUR_epoq_IDENTIFICATION&sessionId=SESSION_ID&customerId=CUSTOMER_IDENTIFICATION&qid=RETURN_QID_FROM_SEARCH_REQUEST&productId=CLICKED_PID

Example Integration

You can view an example integration in the epoq demo shop.

Function	Example URL
Typeahead search for the input `"ho"`	`https[]()://search.epoq.de/inbound-servletapi/getSearchResult?tenantId=TENANT_ID&sessionId=SESSION_ID&query=ho&locakey=&style=compact&format=json&limit=20`
Full search for the entry `"hose"`	`https[]()://search.epoq.de/inbound-servletapi/getSearchResult?full&tenantId=TENANT_ID&sessionId=SESSION_ID&orderBy=&order=desc&limit=20&offset=0&locakey=&style=compact&format=json&nrf=&widgetFallback=&query=hose`
Filter `"ladies"`, sort `"price ascending"`, page 2	`https[]()://search.epoq.de/inbound-servletapi/getSearchResult?full&ff=e:search_gender&fv=Damen&tenantId=TENANT_ID&sessionId=SESSION_ID&orderBy=g:price&order=asc&limit=20&offset=20&locakey=&style=compact&format=json&nrf=&query=hose`
Click request	`https[]()://search.epoq.de/inbound-servletapi/clickSearchItem?tenantId=TENANT_ID&sessionId=SESSION_ID&format=json&qid=38af5770-e047-419f-bf65-ea11fa2b4259&productId=PRODUCT_ID`

Parameter

Name	Description	Example
locakey	For which language(s) to search (optional).	en
query	The query to search with.	hoodie
full	A full search is sent. Used to distinguish between AutoSuggest and normal search.	full
ff	`filterfield`: This field from the product feed is to be filtered.	g:product_type
fv	`filtervalue`: The value to compare with. Can be repeated for multiple values. Same field values are OR-linked; different fields are AND-linked.	Tops>Hoodies
orderBy	Specifies which product attribute to sort by. If not provided, sorting is based on relevance.	price
order	Direction of sorting.	desc / asc
limit	Maximum number of results to deliver. Default: `20`.	30
offset	Starting position of results (for pagination). Default: `0`.	20
ie	Encoding of input parameters (if not UTF-8).
oe	Encoding of return format (if not UTF-8).
style	Type of return. Can be `compact`, `onlyId`, or default full mode.	compact / onlyId
format	Format of the returned result.	xml / json
callback	Name of the function that wraps the JSON response (for JSONP).	retFunc
nrf	New result format: easier to read/parse filter format.
qid	Unique query ID of the request. Used for Search Click Feedback.	518769

Return

The service responds with an XML (or JSON) containing appropriate suggestions and/or articles. In case of a full or extended return, the XML contains article information and statistics:

Filter and article information - XML format

<?xml version='1.0' encoding='UTF-8'?><result xmlns='https://epoq.de' xmlns:g='http://base.google.com/ns/1.0' xmlns:e='http://base.google.com/cns/1.0' xmlns:c='http://base.google.com/cns/1.0'><result xmlns='https://epoq.de'><statistics hitcount="1751" prefilter-hitcount="1751"><filter field="g:product_type"><f c="742">Category A</f><f c="701">Category B</f></filter><filter field="g:brand"><f c="32">Brand 1</f><f c="26">Brand 2</f>  </filter></statistics>   <findings>      <finding>         <match-item node_ref="1862"/>                    </finding>       <finding>          <match-item node_ref="2313"/>                   </finding>       ...   </findings>   <items>      <item>         // Above referenced products with all attributes of the catalog      </item>   </items></result>

Filter and article information - JSONP format

jQuery16106622381170703313({"result": {  "qid": {"$": "5435574 "},  "statistics": {"@hitcount": "150","@prefilter-hitcount": "150","filter": [{"@field": "g:product_type","f": [{"$": "Category A","@c": "116"},{"$": "Category B","@c": "29"}]},{"@field": "g:brand","f": [{"$": "Brand 1","@c": "7"},{"$": "Brand 2","@c": "28"}]}]  },  "findings": {"finding":   [    {"match-item":     {      "@node_ref": "26536-BR",      "c:color": {"$": "blue"},      "c:gender": {"$": "women"},      "g:brand": {"$": "Brave Soul"},      "c:categoryID": {"$": "10.03"},      "link": {"$": "https:\/\/www.epoq.de"},      "g:size": {"$": "XL"},      "c:alterPreis": {"$": "34,99"},      "c:condition": {"$": "new"},      "c:main_categoryID": {"$": "10."},      "title": {"$": "Brave Soul Pants & Chinos Trousers"},      "c:main_category": {"$": "Trousers"},      "description": {"$": "Trousers from Brave Soul. 100% Cotton."},      "g:product_type": {"$": "Pants"},      "g:image_link": {"$": "http:\/\/img4.jpg"},      "c:offer": {"$": "OFFER!"},      "g:price": {"$": "18"},      "g:id": {"$": "26856-BR"},      "epoq_tags": {"$": "26796BR"},      "c:size_search": {"$": "XL"}    }}  ]}}});

With the style “compact” the attributes of the found nodes are directly in the match-item tag; with the style “onlyId” they are completely omitted.

Example calls:

https://search.epoq.de/inbound-servletapi/getSearchResult?

full&callback=JQUERY&tenantId=TENANTID&sessionId=SESSIONID&orderBy=&order=desc&

limit=20&offset=0&locakey=&style=compact&format=json&nrf=&widgetFallback=&query=

SEARCH_TITLE

https://search.epoq.de/inbound-servletapi/getSearchResult?

full&callback=JQUERY&tenantId=TENANTID&sessionId=SESSIONID&orderBy=&order=desc&

limit=20&offset=0&locakey=&style=onlyId&format=json&nrf=&widgetFallback=&query=

SEARCH_TITLE

Text and product proposals - XML format

// Suggestions<finding>    <suggestion hitcount="6" field="g:product_type">Hoodies<doc><attribute name="g:id">...<attribute><attribute name="g:brand">...<attribute>...</doc><doc>...</doc><doc>...</doc></suggestion></finding><finding>...</finding>

Text and product proposals - JSONP format

"findings": {"finding":   [    {"suggestion": {"$": "Knives","@hitcount": "115","@field": "g:product_type","doc": []},     {"suggestion": {"$": "Knives-Sets","@hitcount": "3","@field": "g:product_type","doc": [],},  ]}...}});

XML tags and attributes in detail:

Name	Description	Example
qid	The unique query ID of the request.	154c337f-6d20-464b-8ccb-6f863e8332c6
suggestion	Suggestions for the search, without a concrete product.	trousers - delivery->trousers, summer trousers …
match_item	Concrete products found (contains product matches).	`<sub-match attr="g:brand" key="usa" display="usa"/>`
node_ref	Reference to the ID of a product. Catalog details are listed under “item”.	2313
items	All catalog attributes for products referenced in “node_ref”.
doyoumean	Contains terms that the customer might have meant (spell correction suggestions).
statistics	Specification and distribution of search hits according to selected statistics fields, including filtered vs. unfiltered hit counts.
hitcount	Number of hits found.	5
content-matches	Contains entries matching the search query in the Link Finder.
banner-matches	Contains banner management entries matching the search query.