The purpose of this document is to explain a normal requests flow at EmpathyX. Which APIs are we calling, when are we calling them and which parameters are needed...

These requests are already explained under our Empathy Search REST API public documentation

Opening EmpathyX

Once EmpathyX opens, we make 2 requests.

One for the top clicked (Search REST API: TopClicked) products, and another one to get the popular searches (Search REST API: Empathize).

The purpose of this two requests is to show the most popular products and queries when the user has not typed any search query yet. Also, we usually show the user history in this state too, but as it is stored on the `localStorage`, we don't have to make any request.

Top clicked on empty search

Depending on where these top clicked products are shown on the designs (outside of the empathize, or inside of it), we send `empty_search` or `empathize_recommendations` as the origin parameter to the request, so the results come with an `ebTagging` property with the proper tagging URLs we need to call to when the user triggers one of those events (add to cart, click, or conversion).

For example, if the top-clicked products are shown outside the empathize we use this request:

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/topclicked?lang=es&store={store}&scope=desktop&warehouse={warehouse}&catalogue={catalogue}&rows=12&origin=empty_search

On the other hand, if these top-clicked products are shown inside the empathize, we must tag them with the empathize_recommendations origin, using this call:

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/topclicked?lang=es&store={store}&scope=desktop&warehouse={warehouse}&catalogue={catalogue}&rows=8&origin=empathize_recommendations

Popular searches

Popular searches are displayed commonly inside the empathize. For retrieving them, we just have to make a call to the empathize (Search REST API: Empathize) endpoint without a query.

Whenever a user clicks on one of these suggestions, we must track the query (Tagging REST API: TrackQuery), with the origin empathize_trending.

Next queries suggestions

This suggestions depends on the last query we have done. It will be shown when this last query has next queries associated. They are displayed differently depending on whether there is query in the search box or not.

To visualize these kind of suggestions we have to make a call of this type:

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/nextqueries?q=camiseta&lang=es

Suggestions

This is the call we use to show suggestions requested to the empathize endpoint:

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/empathize?q=camisa&lang=es&store={store}&warehouse={warehouse}&catalogue={catalogue}&rows=5

Search response

This is the call we use to retrieve search results:

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/searchv2?q=camisa&catalogue={catalogue}&rows=24&start=0&scope=desktop&lang=es&store={store}&warehouse={wharehouse}&origin=default&user=03f5c57a-69e6-4cee-8f29-e81bfea1075e&session=570096c3-43cf-4cbd-8e7a-75517150ed4c&user_type=recurrent

Related tags

Related Tags are a great tool to help users articulate a more specific query. They provide refinement suggestions that are inferred through collaborative filtering 

To visualize these related tags we have to make a call of this type:

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/relatedtags?q=camisa&lang=es

Next queries

Next Queries: users get exposed (see use cases below) to the queries that are contextually relevant to their current ones. Next queries are generated from all users who previously searched with that/those terms, what they did next.

To visualize text queries we have to make a call of this type:

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/nextqueries?q=camisa&lang=es

Partial results

When we search for more than one term and have no results, this functionality will show us the results for each of the queries.

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/searchv2?q=camisa%20calcetines%20&catalogue={catalogue}&rows=24&start=0&scope=desktop&lang=es&store={store}&warehouse={warehouse}&origin=default&user=03f5c57a-69e6-4cee-8f29-e81bfea1075e&session=570096c3-43cf-4cbd-8e7a-75517150ed4c&user_type=recurrent

Top clicked (no results)

This is the call we make to show top clicked when a user´s query has no results:

https://api.empathybroker.com/search/v1/query/INSTANCE_ID/topclicked?lang=es&store=INPUT_PARAMETERS&scope=desktop&warehouse=INPUT_PARAMETERS&catalogue=INPUT_PARAMETERS&rows=12&origin=no_results