Search REST API: Search & Tagging

Overview

The purpose of this guide is to provide the steps required to integrate search service via REST API and use the returned tagging urls for each event (query, click, add2cart, ...).

Service URL

URL_SEARCH/INSTANCE_ID/search?INPUT_PARAMETERS

URI Parameters

Parameter Name	Scope	Description	Type	Default Value
q	search	The query for the request	String
lang	search & tagging	Set the language used on this request	String
session	search & tagging	Set the session used on this request	String
user	search & tagging	Set the user used on this request	String
scope	search & tagging	Set the scope used on this request	String
origin	tagging	Set the origin of the request (default, GA, partials, ...)	String
start	search	The number of results to omit from the start of the result set (search pagination)	Integer	0
rows	search	Number of results to return (search pagination)	Integer	10
filter	search	Set query filters to apply	String
facet	search	Set query facets to return	String
sort	search	Sort results	String
jsonCallback	search	Name of the callback that will be executed after the request	String
suggestions.suggestion.docs	search	Number of results to include for each suggestion	String

Search functionalities

Sorting

First of all, you need to send a request with the fields that you want to use for this purpose (ie: price). Then you'll be able to use the sort param to sort the results.

The request param used for this purpose is sort and the format of the value is: field order

Note: this param can be send only one time.

Below, you can find some samples for sorting:

title A-Z

sort=name_sort asc

title Z-A

sort=name_sort desc

price min to max

sort=price asc

price max to min

sort=price desc

Faceting

First of all, you need to send a request with the fields that you want to use for this purpose (ie: category). Then you'll be able to use the facet param to request facets.

Note: to add more facets to the query, you should simply repeat the facet parameter.

Below, you can find a sample to request a facet over brand_facet field:

facet={!ex=brand_facet}brand_facet

Filtering

...

Code examples

NOTE: The following code is just an example, don't copy & paste this for your use

Response format

There are different output formats depending of the search results.

Results + topTrends (empathize) (including categories for the most popular query)

By default, the service will return two JSON nodes, one for the search results (content) and another one for the topTrends (more popular queries and categories for the first one).

Moreover this JSON includes one node per product with the tagging urls and one additional node with the search tagging url.

Default Output Format

{
  content: {
    numFound: 123,
    docs: [],
    facets: [],
    [... more fields ...]
  },
  topTrends: [],
  ebTagging: {
    query: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/query?q=QUERY&scope=default&lang=es&totalHits=10&page=1"
  }
}

According to the example:

numFound → number of the documents returned by the service.
docs → Json array with the documents returned by the service. Each one will contain all the fields configured to be returned by the search service.
topTrends → Popular trends, including category facet for the first one.
ebTagging.query → URL to send the query associated tagging event to our tagging service.

Docs content

docs: [
  {
    name: "Samsung Galaxy Note 10.1",
    [... more fields ...]
	ebTagging: {
	  click: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/click?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  add2cart: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/add2cart?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  wishlist: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/wishlist?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  conversion: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/conversion?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4"
	}
  },
  {
    name: "Samsung SNH-1010N Smartcam",
    [... more fields ...]
	ebTagging: {
	  click: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/click?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  add2cart: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/add2cart?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  wishlist: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/wishlist?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  conversion: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/conversion?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4"
    }
  },
]

According to the previous example:

ebTagging.* → URLs to send the product associated tagging events to our tagging service.

TopTrends content

topTrends: [ 
  {
    title: "<b>sams</b>ng",
    title_raw: "samsung",
    facets: [
      {
        facet: "rootCategories_facet"
        values: [
          {
            value: "Mobile Phones",
            count: 5,
            filter: "{!tag=rootFilter}rootCategories_facet:Mobile Phones"
          },
          {
            value: "Phone Accessories",
            count: 3,
            filter: "{!tag=rootFilter}rootCategories_facet:Phone Accessories"
          }
        ]
      }
    ]
  },
  {
    title: "<b>sams</b>ung galaxy",
    title_raw: "samsung galaxy"
  },
  {
    title: "tablet <b>sams</b>ung",
    title_raw: "tablet samsung"
  }
]

Facets content

facets: [
  {
    facet: "brand",
    values: [
      {
        value: "samsung",
        count: 13,
        filter: "brand:samsung"
      },
      {
        value: "fitbit",
        count: 1,
        filter: "brand:fitbit"
      }
    ]
  }
]

Spellcheck + topTrends (empathize)

The search engine can detect grammatical errors and automatically correct it, for example searching by "sammsung" the system will suggest "samsung" in the spellchecked node.

Default Output Format + spellcheck

{
  content: {
    numFound: 2,
    docs: [],
    facets: [],
    spellchecked: "samsung"
  },
  topTrends: [],
  ebTagging: {
    query: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/query?q=QUERY&scope=default&lang=es&totalHits=10&page=1"
  }
}

Suggestions + topTrends (empathize)

For example searching by "samsung panasonic" the search engine detects than there're no products with both terms but there are products with each term separately.

Default Output Format + suggestions

{
  content: {
    suggestions: [
      {
        suggestion: "panasonic",
        numFound: 101,
        docs: [
          {
            name: "Panasonic KX-TG 8621",
            [... more fields ...]
		    ebTagging: {
	  	      click: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/click?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	          add2cart: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/add2cart?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	          wishlist: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/wishlist?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	          conversion: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/conversion?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4"
	  	    }
          },
          {
            name: "Panasonic KX-TGP 550",
            [... more fields ...]
		    ebTagging: {
		  	  click: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/click?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	          add2cart: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/add2cart?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	          wishlist: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/wishlist?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	          conversion: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/conversion?q=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4"
		    }
          }
        ]
      },
      {
        suggestion: "samsung",
        numFound: 14,
        docs: [
          {
            name: "Samsung Galaxy Note 10.1",
            [... more fields ...]
		    ebTagging: {
		      ...
	        }
          },
          {
            name: "Samsung SNH-1010N Smartcam",
            [... more fields ...]
		    ebTagging: {
		      ...
		    }
          }
        ]
      }
    ]
  },
  topTrends: [],
  ebTagging: {
	query: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/query?q=QUERY&scope=default&lang=es&totalHits=10&page=1"
  }
}

The suggestions node will contain one or more suggestions for each term or combination of terms contained in the query typed by the user.

suggestion → term suggested by the search engine
numFound → number of results that the search engine will return searching using this suggestion
docs → By default, the search engine will return a sample of the results using this suggestion

Empathy Knowledge Base

Search REST API: Search & Tagging

Overview

Service URL

URI Parameters

Search functionalities

Sorting

Faceting

Filtering

Code examples

Response format

Results + topTrends (empathize) (including categories for the most popular query)

Spellcheck + topTrends (empathize)

Suggestions + topTrends (empathize)

Related articles

Search REST API: Search & Tagging

[data-colorid=c48swobb44]{color:#333333} html[data-color-mode=dark] [data-colorid=c48swobb44]{color:#cccccc}[data-colorid=yzccm94icq]{color:#333333} html[data-color-mode=dark] [data-colorid=yzccm94icq]{color:#cccccc}Overview

Service URL

URI Parameters

Search functionalities

Sorting

Faceting

Filtering

Code examples

Response format

Results + topTrends (empathize) (including categories for the most popular query)

Spellcheck + topTrends (empathize)

Suggestions + topTrends (empathize)

Related articles

Overview