Search API


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.

  1. 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.
  2. You will receive a code snippet as a placeholder for the frontend of the intelligent search function, which you integrate into your online shop.
  3. We create the search widget according to your requirements and it takes over the display of filters and search results.
  4. We check the search field and filter functions, test weighting, ranking and error tolerance and optimise these settings.
  5. 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.


The unique identification of your online shop.

(will be assigned to you by us)

customerId A unique customer number of the shop visitor; this can be passed on to some functions as soon as it is known. If the customer number is not (yet) known, "nothing" can be transferred.
sessionId A unique identification of a customer's session in the online shop.



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






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








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)



















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







Example Integration

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

Function Example
Typeahead search for the input "ho"

tenantId=TENANT_ID &sessionId=SESSION_ID&query=ho&locakey=


Full search for the entry "hose"



After filtering "ladies", sorting "price ascending" and paging "second page"




Click request





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. To distinguish between AutoSuggest and normal search. full
ff filterfield: This field from the product feed is to be filtered. g:product_type

filtervalue: The value to compare with.

The parameters ff and fv can be repeated as often as required.

If several filtervalues are specified for the same field, they are normally "OR"-linked.

Different fields are always linked "AND".


Specifies the catalog by which attribute should be sorted.

If no "orderBy" is specified, the standard sorting of the search is based on relevance to the search term and the knowledge base of epoq.

This should normally always be the first sort on the search results page.

order Direction of sorting (ascending or descending).




The maximum number of results to be delivered.

default: 20


From which position the results should be delivered (for the following pages).

default: 0

ie Specifies the encoding of the input parameters if they are not in UTF-8.  
oe According to the encoding, a return format other than UTF-8 can be selected here.  

Specifies the type of return.

In addition to normal return, there is also a compact mode and a mode in which only the product IDs are returned.




Format in which the search result should be returned.

Possible values: xml/json

callback Name of the function that encloses the JSON, making it JSONP. retFunc
nrf new result format: Somewhat easier to read and parse filter format.  
qid The unique query ID of the request. For Search Click Feedback only. 518769



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='' xmlns:g='' xmlns:e='' xmlns:c=''>

<result xmlns=''>

<statistics hitcount="1751" prefilter-hitcount="1751">

<filter field="g:product_type">

<f c="742">Category A</f>

<f c="701">Category B</f>


<filter field="g:brand">

<f c="32">Brand 1</f>

<f c="26">Brand 2</f>





         <match-item node_ref="1862"/>             



          <match-item node_ref="2313"/>            






         // Above referenced products with all attributes of the catalog





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:\/\/"},

      "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:








Text and product proposals - XML format

// Suggestions


   <suggestion hitcount="6" field="g:product_type">Hoodies


<attribute name="g:id">...<attribute>

<attribute name="g:brand">...<attribute>











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. <sub-match attr="g:brand" key="usa" display="usa"/>
node_ref Reference to the ID of a product. Catalog details of the product are listed under "item". 2313
items All catalog attributes for products referenced in "node_ref".  
doyoumean Contains terms that the customer might have meant.  
statistics Specification and distribution of search hits according to the selected statistics fields. In addition to the current number of hits (hitcount), the number of hits that would have been achieved without the filter can also be displayed.  
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.  


Was this article helpful?