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.

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.

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.

Parameter

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: