Search REST API: Browse & Tagging

Overview

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

Step-by-step guide

Service Name

browse

Service URL

URL_SEARCH/INSTANCE_ID/browse?INPUT_PARAMETERS

Input Parameters

ParameterDescriptionData TypeMandatory
categoryIdThe category that has been clicked to filter byStringYes
langSet the language of the queryStringYes
startIt is used to paginate results from a queryIntegerYes
rowsIt is used to paginate results from a queryIntegerYes
filterSet query filtersStringNo
boostboosting query in lucene query formatStringNo
facetSet query facetsStringNo
sortSort resultsStringNo
jsonCallbackName of the callback that will be executed after the requestStringNo

Sorting

Send us a request with the fields you want to use for SORTING and we will configure it. 

You can find below some code samples of the api syntax 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

Boosting

Boosting allows you to modify the default ranking pushing to the top the documents matching the specified queries. 

Boosting Nike and Rebook products
boost=brand:Nike^2.1 OR brand:Rebook^1.3

boost parameter can be specified multiple times, so multiple queries could be specified as part of a single query using OR (as specified above) or specifying those queries in individual boost parameters.

boost=brand:Nike^2.1&brand:Rebook^1.3

Faceting

Send us a request with the list of fields that you want to use for FACETING and we will add it to the config.

Example of the api syntax for faceting, with the field brand_facet:

facet={!ex=brand_facet}brand_facet

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

Output

There are different outputs depending of the search results.

Results 

By default, the service will return one node for the search results (content).

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

{
    content: {},
	ebTagging: {
    	browseCategory: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/browseCategory?categoryId=QUERY&scope=default&lang=es&totalHits=10&page=1...."
  	}
}
{
    content: {
        numFound: 14,
        docs: [
                {
                    name: "Samsung Galaxy Note 10.1"
                },
                {
                    name: "Samsung SNH-1010N Smartcam"
                },
        ],
        facets: [
                {
                    facet: "brand",
                    values: [
                        {
                            value: "samsung",
                            count: 13,
                            filter: "brand:samsung"
                        },
                        {
                            value: "SBS",
                            count: 1,
                            filter: "brand:SBS"
                        }
                    ]
                }
        ]
    }
}


According to the previous 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.
  • facets → filters, will contain one entry for each facet contained in the request using the facets param or directly configured in the search service by the EB Team.
  • ebTagging.browseCategory → URL to send the query associated tagging event to our tagging service.


Docs content
docs: [
  {
    name: "Samsung Galaxy Note 10.1",
    [... more fields ...]
	ebTagging: {
	  browseProduct: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/browseProduct?categoryId=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  browseAdd2Cart: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/browseAdd2Cart?categoryId=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  browseCheckout: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/browseCheckout?categoryId=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: {
	  browseProduct: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/browseProduct?categoryId=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  browseAdd2Cart: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/browseAdd2Cart?categoryId=QUERY&scope=default&lang=es&url=PRODUCT_URL&page=1&productId=PRODUCT_ID&title=PRODUCT_NAME&type=4",
	  browseCheckout: "URL_EMPATHYBROKER/tagging/v1/track/CLIENT_ID/browseCheckout?categoryId=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.