Implement Find with APIs

Using APIs to implement Find requires a decent understanding of what each API can do, including all of the many parameters that can be used. This document is intended to aid those tasked with implementing Find using the Find APIs.

Requirements

Before you start using the API you need to ensure that the following has been set up and configured:

Find placement - usually search_page.find

Index builds have been scheduled

Attributes have been added to the feed and configured correctly. Specifically attributes that need to be returned for any HTML rendering

You can verify the above by making a simple request and ensure you are getting the expected data returned.

Implementation Options

It is very important to define the functionality and implementation options before you start integrating. To do this a good understanding of what each API can and cannot do is very important. Below are three implementation options, by way of example.

Instant Search + Autocomplete

With an API implementation you can simulate the implementation of the Algonomy overlay by implementing the search API request client side and rendering the search results, including all facets and number of results found, as the shopper is typing in an overlay that covers the underlying web page. This type of implementation means that all attributes required to render the HTML need to be returned in the response.

Adding the Autocomplete API, while the shopper types, search terms are displayed and if you click or hover over a term, the results can be updated instantly sending a Search API request with the term.

Server Side Search Page Result + Autocomplete

With this option the search API request will be made server side once the shopper has typed in the full search word and has submitted the search query which leads to a new search results page. With this implementation internal lookups can be done for HTML rendering.

Autocomplete can be implemented as a simple list or can be divided by categories, brands and products. Functionality of what happens on the click of the term needs to be considered carefully. Terms are de-duplicated so subcategories with the same name will only appear once with the category id of with the highest aggregated sales so direct navigation could be restrictive and/or have undesired results.

If more detailed information is required from Autocomplete the search API can be used for search preview functionality (see below)

Server Side Search Page Result + Search Preview

With this option the search API request will be made server side once the shopper has typed in the full search word and has submitted the search query which leads to a new search results page. With this implementation internal lookups can be done for HTML rendering.

The Search API can be used for search preview functionality. This means that as the user types the search API can be called and by parsing the information returned a Search Preview can be displayed instead of Autocomplete with details such as, but not limited to:

  • Number of products found
  • Product details with layout
  • Categories and number of items found in the category for the query
  • Brands and number of items found of that brand for the query

Autocomplete API Request Parameters

You can find all the parameters on the API documentation page but below are a few additional details for some of these parameters:

rows - By default 5 terms are returned. Use this parameter to request a different number of search terms to return.

log - this is false by default. To have analytics and reporting set this to true.

filter - the filter is applied to the type of search term to be returned (Product, Brand, Category and Top Search terms) - but not any other product attributes. Example: filter=type%3ABRAND+OR+type%3ACATEGORY will only return search terms matching Brand or Category

Autocomplete API Response Objects and their use

You can find all the response objects on the API documentation page, but below are a few additional details for some of these values

TOPTRENDS will only be returned when search terms are logged in production.

value - Indicates popularity score of the suggestion. The score is based on the sales of the product terms and aggregated sales for Brand and Category.

id - Based on the id and the type of suggestion (brand, product, category) you can optionally allow the shopper to directly navigate to a product, category or brand by composing the link with the id/

Search API Request Parameters

You can find all the response objects on the API documentation page but below are a few additional details for some values:

sessionId, userId and rcs

Although the sessionId, UserId and rcs parameters are optional and not required to get an API response, these three parameters are of utmost importance for a best practice implementation so you will get the most out of your search solution and in particular the personalization.

You should always send the sessionId which needs to be the same id sent in the core implementation and if the user has been identified, either through a login or a persistent cookie, the userId should be passed. The userId will allow personalization across different browsers, devices and platforms.

The rcs parameter should always be passed in the request. This “rcs" parameter is encrypted. It contains various Algonomy IDs including the Algonomy USER GUID which is used for personalization when the userId is unknown. The new rcs value, returned in the response should update (or create) the first party rr_rcs cookie.

You can find documentation for implementing the Algonomy cookie as a first party cookie here: Integrating RR cookies as First party cookie for RecsForPlacements

filter

  • Each type of filter is added with the filter parameter repeated e.g. filter={!tag=ColorGroup}Color:("Black")&filter={!tag=product_category_external_id}product_category_external_id:1863
  • You can compose and add filters programmatically or you can add them directly as they were returned in the facet
  • The "tag" filter syntax is used return all the different options for a facet even after filtering. E.g. if you have a facet called "letter" with the following values: "A", "B", and "C". If you filter by "A" you will see only documents that contain the a letter=A and the "letter" facet will show only the option "A". If you send the filter with the "tag" syntax you will see "A", "B" and "C" options for the facet values.
  • Single attribute with more than one value can be filtered on with AND and OR operators programmatically.
    • To programmatically apply AND condition, just repeat the filter with the value as returned by the facet, e.g. filter={!tag=color}color:"red"&filter={!tag=color}color:"pink"
    • To programmatically apply an OR condition the q.op parameter must be added inside the local parameter section, in addition to the operator within the filter value, enclosed by parenthesis with the operator OR. E.g. filter={!tag=material q.op=OR}material:("Leather" OR "Cotton"). Please note that the OR operator needs to be uppercase. Limitation: This syntax is not integrated into the Find response. For example, the OR category filter syntax does not return the child categories in the response facets.
  • Price facets include min. and max. values so client can create slider instead of using the pre-configured facets
    • ”min": 997,
    • "max": 99900,"values": [{
    • "filter": "{!tag=product_effectiveprice_cents}product_effectiveprice_cents:[0 TO 5000]",
    • For slider faceting can be transformed into
    • filter={!tag=product_effectiveprice_cents}product_effectiveprice_cents:[100 TO 6000]

sort

The default is a personalized sort. You can also sort by default catalog fields such as price nd name or any product attribute that you specified in your catalog.

Product attributes are considered as strings and not numerical values, except for default price fields. If you have a numerical value you want to sort on, e.g. Discount percentage, make sure you add leading zeros.

The format for adding the sort value is sort=[attribute name]+(asc|desc) . To sort alphabetically on the name ascending it would be:

sort=product_name+asc

Always use the automatically calculated product_effectiveprice_cents attribute for sorting on prices. This attribute combines the regular and sales prices passed in the feed.

log and findCallType

Set log to "true" to log the search request event for analytics (default is false). NOTE: Only the values "true" and "false" will work.

Set findCallType to "direct" or omit (default is direct) for pure server side implementations. For Instant Search implementations or Pre-search requets set this parameter to "overlay" to avoid tracking each letter as a search term event. To forward the search request event to the real time statistics service use the searchTrackingURL when a shopper has clicked on a product or presumably has finished typing (e.g. 3 seconds after last typed letter).

facets

  • Category facets can have children – subcategories
  • Subcategories will only be returned for a category that is filtered on - in the future the whole category hierarchy will be returned

Search API Response Objects and their use

You can find all the response objects on the API documentation page but below are a few additional details for some values:

rcs: as per above, this value needs to be used to update the first party cookie and returned in the next request, which could also be other server side solutions like Discover, Recommend and Engage

searchTrackingUrl: This will only if the findCallType in the request had Overlay and is to be used for real time analytics tracking (see above)

docs: The list of products that match the search term

"clickUrl": Needs to be sent to Algonomy when the shopper clicks on a product in the search results. Either by adding this link to the product or by using an onclick event and ajax to send the link to Algonomy.

Note: If the clickUrl is used directly on the product and requires the redirect to the product page the parameter &redirect=true needs to be added to each clickUrl.

spellchecked: If there was a typo that was auto-corrected by our engine, the corrected term will be specified here. This can be used to communicate this to the shopper. E.g. "Maybe you were looking for "shirts?" The spellcheck result is based on string distance and number o matching products . E.g. for the misspelling “shrt” if a catalog has more ”shirts” than “shorts” it will default to “shirts” and vice versa if a catalog has more ”shorts” than “shirts” it will default to shorts. Setting up a directional synonym rule for “shrts” allows the customer to override this. The query will have already searched on the auto-corrected term.

addtoCartParams: these add to cart parameters can be used for add to cart events from the search results page or the immediate product page navigated to from the search result page that. The add to cart tracking for Find does not replace the Core implementation add to cart tracking. The parameters should be appended to the Track Add to Cart API for server side core implementation or for client side core implementation you can use the single parameter values and add these to the as explained here.

links: Three types of links can be returned. Banner and sponsored links contain an image and/or other content that needs to be displayed. Any link that is returned in the directlink object is a that usually is used to automatically redirect the shopper to. The link information is set up by in the portal by the business users.