Search API

Copy

GET http://recs.richrelevance.com/rrserver/api/find/v1/<API_KEY> or GET http://integration.richrelevance.com/rrserver/api/find/v1/<API_KEY>

Note: If you are making the Search API requests directly from the web browsers, then you are advised to upgrade the API endpoint to our new First party data capture domain https://recs.algorecs.com in place of https://recs.richrelevance.com. Please contact your Algonomy consultant to configure the click URLs to also point to https://recs.algorecs.com.

Returns product results for a search term. This is the main API to initiate search requests. You can specify multiple parameters such as number of products to return, page number, filters to apply, etc to refine the search request further.

The response is a list of product information and facets needed to render a search results page. It could change based on search attributes settings available on FIND dashboard. (See below for more details on the response object).

When using the Search API for autocomplete as product suggestions, “instant search,” or “inline search,” the following parameters must be included to ensure optimal performance:

findCallType=overlay
facet.enabled=false
ngramSearch=true
fl=linkId, name, imageId, … (limit to only the necessary fields for rendering product suggestions)
rows= (set to the exact number of products to be displayed)

Parameters

Required parameters are followed by the optional parameters in alphabetical order.

Name	Data Type	Required or Optional	Description
lang	String	Required	Recommended to use the two character ISO code such as "en" for english. Or use codes used in the feed or in the streaming catalog API.
placement	String	Required	Page path to reuse: /Template:API/placements
query	String	Required	The text to search. Example: query=shoes There is a limit to the size of a query. It is currently limited to 75 characters.
rows	Integer	Required	Rows describe how many results to return back. If you want to show 20 products on the page, set rows=20.
start	Integer	Required	The starting position of the results you want for the specified query. It's a zero indexed system. For example if you want the first 20 results, you will set start=0, if you want the next 20 results (21-40), you will set start=20.
sessionId	String	Required	Identifies a single visit by a shopper. Sessions are used by behavioral models (to scope user behavior in a shopping session.) and reporting metrics. Example: sessionId=93484
userId	String	Required	User ID. A unique string to identify each shopper (user). All shopper behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to Algonomy in other applications. Example: userId=0982347 If no userId is given, search results will be based on session based history (sessionId) and previous view/purchase behavior through the rcs parameter/cookie implementation. The search results will still take Wisdom of the Crowd behavior into account.
rcs	String	Required	Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response. Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers. Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API.
The following parameters are optional.
callback	String	Optional	Name of the JavaScript function that JSON data will be passed to. It must be specified for JSONP. The value of this parameter is used as the name of the js function in the response. Example: callback=products_returned
channelId	String	Optional	Channel ID is used by some Algonomy reports to differentiate channels such as mobile or desktop. Example values are: WEB, WEB_PHONE, WEB_TABLET. It can be any API client key that an Algonomy consultant has set up for a customer.
facet	String	Optional	Specify which fields/attributes you want facets for in the response. If you don't specify any, then all attributes configured to be facetable (in the dashboard) will be returned in the response. For a list of all applicable fields see section below called "Fields".
facetDepth	Integer	Optional	Controls the number of category levels returned in the Category Facet filter. facetDepth < 0 - Depth parameter is not considered, Standard behavior is applied, i.e. only the top level is returned on the first request and the children are only returned after the top level selection. facetDepth == 0 - Return no categories to filter. facetDepth > 0 - The category depth is built until max depth value level or the depth specified in the parameter is reached. Example: facetDepth=5 will return 5 depth level if the category hierarchy has all that levels. If the hierarchy has only 3 levels, then only 3 depth level will be returned.
facet.limit	Integer	Optional	Default value = 100 Can be a +/- integer value A negative value means that Solr will return unlimited number of constraint counts. More information: https://lucene.apache.org/solr/guide/6_6/faceting.html#Faceting-Thefacet.limitParameter facet.limit is only applied to the following responseStyles: fullResponse and facetsOnly. Note: facetDepth has priority over facet.limit and facet.mincount. When facetDepth is present, facet.limit and facet.mincount are ignored for category field (product_category_name)
facet.mincount	Integer	Optional	Default value = 0 Can be an integer value. For More information see: https://lucene.apache.org/solr/guide/6_6/faceting.html#Faceting-Thefacet.mincountParameter Note: facetDepth has priority over facet.limit and facet.mincount. When facetDepth is present, facet.limit and facet.mincount are ignored for category field (product_category_name)
filter	String	Optional	Apply a filter to the search term. You can apply multiple filters. For a list of all applicable fields see section below called "Fields". The response (see section called "Response" below) also provides you a list of facets and how to filter by the facets. Here's an example of how you filter for the brands "adidas" and "puma" filter=product_brand:"adidas"&filter=product_brand:"puma" Another filter example with AND and OR: filter={!tag=material q.op=OR}material:("Leather" OR "Cotton"). The "tag" filter syntax is used return all the different options for a facet even after filtering.
findCallType	String	Optional	Specifies the call type from the client. Default is 'direct'. direct - If log is true, record the search request event within the analytics system and also forward the search request event to the real time statistics service. overlay - If log is true, record the search request event within the analytics system, but do not forward the search request event to the real time statistics service. In that case, the searchTrackingUrl should be used to provide real time statistics.
fl	String	Optional	Field List The field list parameter limits the information included in a result set to a specified list of fields. The result set will only include the fields specified in the field list plus id and score (which are always returned). Each field must be "storable" or its values won't be returned. The default is to return all storable fields. The field list is specified as a comma-separated list of field names. Example: fl=size,color will return: id score size color If blank, wildcard or null are used, the following will occur: fl= (blank) Returns all storable fields fl=* Returns all storable fields fl=null No fields are returned Notes: To return clickURL, please use linkID. Using linkId will return both the clickURL and linkID. clickURL is a derived attribute and doesn't have search attributes associated with it such as "storable". Example: Example: fl=size,color,linkId will return: id score size color linkID clickURL
log	Boolean	Optional	If set to true this will log the search request event for analytics. The default behavior is for this to be false. Note: Only the values "true" and "false" will work.
mm	Integer	Optional	Minimum Match The valid values for mm (minimum match) with example param in solr are as : Positive integer 3 Negative integer -2 Percentage 75% Negative percentage -25% An expression 3<90% Multiple conditional expressions involving > or < signs 2<-25% 9<-3 For more information see: https://lucene.apache.org/solr/guide/6_6/the-dismax-query-parser.html#TheDisMaxQueryParser-Themm_MinimumShouldMatch_Parameter)
ngramSearch	Boolean	Optional	N-grams are like a sliding window that moves across a word - a continuous sequence of characters of a specified length which in Find is defaulted to 1. Ngram search is often used with an auto-complete/type ahead feature. For example, as a shopper types each character in the search box, there is a match based on the characters entered. Some Find customers use the Find API for auto-complete of products instead of the autocomplete API. It is important for them to be able to set ngramSearch=true as part of the Find query. It is recommended to set to ngram=false for general product queries. There can be a system wide setting for ngramSearch in the site configuration which an Algonomy consultant sets up. If it is not set up in the site configuration, the default is true. This parameter will over-ride the setting in the site configuration as well as the default value. ngramSearch=true/false.
searchAttributeBoosts	String	Optional	''searchAttributeBoosts'' specifies the search attribute name, value, and amount of boost in the following format "<search-attribute-name>:<value>^<boost-amount>". For example: "product_brand:LargeSize^0.25" For searchAttributeBoosts, a positive boost value increases the weight of the product with that attribute:value combination. A negative boost value moves the product to the end of the search results list.
pref	String	Optional	Shopper’s referrer prior to viewing the page. Used for reporting and merchandising. This is highly recommended. Example: pref=http://www.google.com
privm	Boolean	Optional	True/false. If set to true, privacy mode is enabled for the request. In privacy mode, user affinity data is ignored, and search results are generated without personalization based on behavioral data. This ensures that search results respect user consent preferences and do not use behavioral data for users who decline tracking. Example: privm=true
region	String	Optional	Region Identifier
responseStyle	String	Optional	The responseStyle parameter controls the result set that is returned. By default all fields which are tagged as "storable" are returned as well as facets (facetable). Personalization and boosts will also be applied if they are setup and turned on. The responseStyle parameter has a number of options which are detailed below. fullResponse - Default. Result set limit is 512 rows. idAndScores - Returns just the product Ids and scores. The result set limit is up to 10,000. facetsOnly - Returns just facets and not product or content. There is also no limit on facets being returned. However the default number of items returned within a facet is 100 and can be controlled by the facet.limit parameter. Since products and content are not returned, the rows parameter is automatically set to 0. There is no need to provide the rows parameter in a facetsOnly query. productsOnly - Returns products only. Does not return facets and also does not apply personalization, boosts, links, merchandising rules or spell check. One use case is when personalization is not required and the customer wants to display "new" products and can sort by date. The purpose is to only bring back the required information and to avoid unnecessary processing. Example of idAndScores: Request: Copy `https://...start=0&rows=10000&facet=0&query=phone&responseStyle=idAndScores` Response: Copy `....{ "docs": [ { "score": 1, "id": "58481" } ......}`
sort	String	Optional	Specify how you want to sort a result list of either products or reference content. The default is a personalized sort based on "score" (sort=score desc). You can instead sort by any attribute that you specified in the search attributes to be sortable. For a list of all applicable fields go to the "search attributes configuration" in the portal. We recommend that in addition to the personalized relevant sort (the default) you give options for shoppers to sort by these fields. product_rating (Average rating from reviews) product_effectiveprice_cents (Combined price and sale price) product_release_date (The newness of the product) Also, specify whether you want the sort to be in ascending or descending order. Allowed values are: "asc" or "desc". One must be specified. Example: sort=product_release_date desc You can specify more than one field, and the field name can have spaces. You can also still have the score as the primary sort followed by a secondary sort as in this example: sort=score desc, field name asc Note: Multi-value attributes are not sortable. If the sort parameter is not correct the default will be used which is "score desc".
spellcheck	String	Optional	Find will spellcheck a query term when the the initial query has 0 results. It then executes a second query using the recommended spellchecked term. The spellcheck is based on all indexed searchable attributes except for wisdom of crowd attributes and product_external_id. The default is "jaro" which is a similarity algorithm to compare short strings. The following spellcheck options are provided in order to return the best suggested term(s) and meet customer expectations. jaro - default, JaroWinklerDistance is a similarity algorithm to compare short strings. off - spellcheck is turned off, useful when the query is a bar code or other product code. hits - return the suggested term that has the most hits suggest - a list of suggestions is returned and is useful when implementing "did you mean". Below are further details and examples. jaro - default -not explicitly provided in query If the spellcheck parameter is not explicitly set, the "spellchecked" field is returned. Copy `query=seattle1 Response will include: "spellchecked" : "seattle"` jaro - parameter provided in query - equivalent result to "query=seattle1". Note that the "spellcheck" parameter will provide the type of spellcheck and the suggested term. Copy `query=seattle1&spellcheck=jaro Response will include: "spellchecked" : "seattle" "spellcheck" : { "spellcheckType" : "jaro" "spellchecked" : "seattle" }` off Copy `query=seattle1&spellcheck=off Response - "docs" is empty "spellcheck" : { "spellcheckType" : "off" }` hits - see the "suggest" list below to understand why "settler" is returned Copy `query=seattle1&spellcheck=hits Response will include: "spellchecked" : "settler" "spellcheck" : { "spellcheckType" : "hits" "spellchecked" : "settler" }` suggest A set of suggested terms are returned that could be used for "did you mean" and to build an alternate query. This option does not automatically execute a second query as is the case for "jaro" and "hits". Two lists are returned: "spellcheckSuggestions" and "suggestionsWithHits" (number of hits for suggested terms is provided). Copy `query=seattle1&spellcheck=suggest Response - "docs" is empty "spellcheck" : { "spellcheckSuggestions" : { "seattle1" : ["seattle", "seat tl e1", "settler"] }, "suggestionsWithHits": {"seattle":8, "settler":20}, "spellcheckType": "suggest" }` suggest - multiple search terms Copy `query=seattle1 washington1&spellcheck=suggest Response - "docs" is empty "spellcheck" : { "spellcheckSuggestions" : { "seattle1" : ["seattle", "seat tl e1", "settler"] "washington1" : ["washington", "washing to n1"] }, "suggestionsWithHits": {"seattle washington":8}, "spellcheckType": "suggest" }`
ssl	Boolean	Optional	If set to true, then clickUrl and searchTrackingUrl are returned with https protocol.
tie	Double	Optional	By default the score for each item in a result set is based on the "max" score from one field (plus personalization, boosts etc also play a role). Often many results will have the same score. "Tie" is a Solr parameter which takes into account the hits on other fields. It applies the following calculation: score = [score of the top scoring subquery] + tie * (sum of other hitting subqueries) It is recommended to set "tie" to a low value 0.1 in order that the sum of the other fields doesn't over power the key field with the most hits. Values can range from 0.0 to 1.0 with the default set to 0.0 "tie" can be a parameter in a Find API query or in the search configuration in the portal. If in the Find API, it will over-ride the value in the search configuration portal. Example Query: ...query=shoes&rows=15&tie=0.1 Further details: https://lucene.apache.org/solr/guide/6_6/the-dismax-query-parser.html#TheDisMaxQueryParser-Thetie_TieBreaker_Parameter
fq	String	Optional	The Filter Query (fq) parameter is an advanced filtering option used in addition to the existing filter parameter. It enables more complex query logic using Solr syntax and offers greater flexibility, though it may impact performance when overused. For more information on fq parameter, see Filter Query (fq).

Example Request

Copy

http://recs.richrelevance.com/rrserver/api/find/v1/<API_KEY>?query=shoes&lang=en&sessionId=sess456&userId=u789&placement=search_page.search1&start=0&rows=20

Example Response

Copy

{
   "request":{
      "apiKey":"showcaseparent",
      "placements":[
         "search_page.sort"
      ],
      "sessionId":"s1234",
      "userId":"u1234"
   },
   "placements":[
      {
         "searchTrackingUrl":"http://localhost:8101/rrserver/api/v1/service/track/search/showcaseparent?query=t&lang=en&user=u1234&session=s1234&channel=WEB&region=&numFound=1956&placement=search_page.sort&page=0&rcs=eF4FwbENgDAMBMCGill4yUls570BcyRgiYIOmJ-7Zb2_5zo2F6KosfReW3gEWCHLO3eK2NAUpOYJ1WmYVEeatWAdPpg_V-4RTg",
         "rcs":"eF4FwbENgDAMBMCGill4yUls570BcyRgiYIOmJ-7Zb2_5zo2F6KosfReW3gEWCHLO3eK2NAUpOYJ1WmYVEeatWAdPpg_V-4RTg",
         "links": {
            "directlink": [
               {
                  "id": "direct-link-id",
                  "title": "direct-link-title",
                   "subtitle": "direct-link-subtitle",
                  "url": "direct-link-url"
               }
            ],
            "banner": [
               {
                  "id": "banner-id",
                  "title": "banner-title",
                  "subtitle": "banner-subtitle",
                  "url": "banner-url",
                  "image_url": "image-ur"
               }
            ],
            "sponsored": [
               {
                  "id": "sponsored-id",
                  "title": "sponsored-title",
                  "subtitle": "sponsored-subtitle",
                  "url": "sponsored-url",
                  "image_url": "sponsored-image-url"
               }
            ]
         },
         "docs":[
            {
               "clickUrl":"http://localhost:8101/rrserver/api/v1/service/track/click/showcaseparent?a=showcaseparent&vg=80015896-f4fe-44c5-41ab-6654e0877e89&pti=2&pa=sort&hpi=0&stn=PersonalizedProductSearchAndBrowse&stid=184&rti=2&sgs=&u=u1234&mvtId=0&mvtTs=1458177239699&uguid=8005b4f0-f4fe-44c5-c846-f553982b6b8f&channelId=WEB&s=s1234&pg=-1&page=0&query=t&lang=en&p=10308694&ind=0&ct=http://labs.richrelevance.com/storre/catalog/product/view/sku/10308694",
               "imageId":"http://labs.richrelevance.com/storre/media/catalog/product/t/-/t-gel-original-shampoo-8.5oz-1e2df9930cf89d1614debdbaa3feaf38.jpg",
               "linkId":"",
               "salePriceCents":798,
               "name":"T-Gel Original Shampoo, 8.5oz",
               "priceCents":798,
               "id":"10308694"
            },
            {
               "clickUrl":"http://localhost:8101/rrserver/api/v1/service/track/click/showcaseparent?a=showcaseparent&vg=80015896-f4fe-44c5-41ab-6654e0877e89&pti=2&pa=sort&hpi=0&stn=PersonalizedProductSearchAndBrowse&stid=184&rti=2&sgs=&u=u1234&mvtId=0&mvtTs=1458177239699&uguid=8005b4f0-f4fe-44c5-c846-f553982b6b8f&channelId=WEB&s=s1234&pg=-1&page=0&query=t&lang=en&p=10339306&ind=1&ct=http://labs.richrelevance.com/storre/catalog/product/view/sku/10339306",
               "imageId":"http://labs.richrelevance.com/storre/media/catalog/product/a/t/atampampt-2000-minutes-rechargeable-us-ampamp-international-prepaid-phone-card-c9152dba32526ce359e426e5bcad0903.jpg",
               "linkId":"",
               "salePriceCents":4488,
               "name":"AT&amp;T 2000-Minutes Rechargeable US &amp; International PrePaid Phone Card",
               "priceCents":6320,
               "id":"10339306"
            }
         ],
         "numFound":1956,
         "placement":"search_page.sort",
         "spellchecked":null,
         "addtoCartParams": "page=1&query=t&lang=en&searchConfigId=123434sdef3222",
         "errors":[],
         "facets":[
            {
               "values":[
                  {
                     "filter":"{!tag=categories_facet}categoryIds:\"871098905\"",
                     "count":842,
                     "value":"Apparel"
                  },
                  {
                     "filter":"{!tag=categories_facet}categoryIds:\"1985805468\"",
                     "count":519,
                     "value":"Beauty"
                  }
               ],
               "facet":"categories_facet"
            },
            {
               "values":[
                  {
                     "filter":"{!tag=brand_facet}brand_facet:\"Generic\"",
                     "count":126,
                     "value":"Generic"
                  },
                  {
                     "filter":"{!tag=brand_facet}brand_facet:\"Hanes\"",
                     "count":77,
                     "value":"Hanes"
                  }
               ],
               "facet":"brand_facet"
            },
            {
               "min":0,
               "max":10000,
               "values":[
                  {
                     "filter":"product_effectiveprice_cents:[0 TO 5000]",
                     "count":126,
                     "value":"0:5000"
                  },
                  {
                     "filter":"product_effectiveprice_cents:[5000 TO *]",
                     "count":77,
                     "value":"5000:*"
                  }
               ],
               "facet":"product_effectiveprice_cents"
            },
         ]
      }
   ],
   "message":"",
   "status":"OK"
}

The table below describes the key fields returned in the search response. These fields contain details necessary for rendering search results, tracking search activity, and facilitating user interactions.


Name	Description
request	The parameters from the request that Algonomy used in processing the request. Typically used for testing purposes.
placements	In almost all cases there should only be 1 placement requested for search. This object will contain all the information needed to render the search results on a page/app. This is a nested field that contains multiple fields: searchTrackingUrl: A URL used for real time search request statistics within the Overlay client-side application. This URL should be invoked by the Overlay application. At the same time, the Overlay application issues search requests with findCallType = 'overlay'. docs: The list of products that match the search term - 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 numFound: How many products in the catalog match the search term and any filters applied. This values is used to communicate to the end user how many products match their search term. placement: The name of this placement. spellchecked: If there was a typo that was auto-corrected by our engine, the corrected term will be specified here. If no spell correction was needed this value will be empty or 'null'. facets: List of all facets that are applicable for the products that match this search term addtoCartParams: parameters that should be appended to add to cart event firing from product detail page of the search result product. links: configured links (URLs) with the search term that was specified the request banner: link to the banner image that should be displayed along with the search results. directlink: link to another page where shopper should be asked to follow. sponsored: link to sponsored content that should be displayed
errors	Reported errors that occurred while processing the request.
facets	facets are returned as part of the placements structure. They power the faceted search navigation experience. Facets contains these fields: 1. values: array of possible facet options for a give type 2. filter: filter query that should be used when the shopper selects this facet option. filter query should be passed as it is to the filter parameter of the subsequent search request 3. count: Number of items matching this facet option. In other words, number of items to expect when filter for this facet is applied to the subsequent search request. 4. value: Display value for the facet 5. child: For hierarchical attributes like categories, Find provides a way to let shoppers navigate through the hierarchy by providing immediate next child categories in the facet values. This is invoked by providing higher level category as a filter. For example, filter=categoryId:root will provide 1st level children of root as facets in the search response. 6. Price min - max: For price facets, Find returns min and max price values for the current search results, to be able to power a price selection slider kind of UI control instead of option boxes for each individual price ranges.
status	We always return 200s. The status object will determine if the request was successfully processed ("OK") or if there was an error ("error"). Callers should check for the "OK" string to verify.
message	If there was an error in the status, then this field will contain information as to why an error occurred.

Fields

Some product attributes shared via the catalog feed have fixed/reserved names and must be described by their canonical name. The table below describes them.

Name	Data Type	Description
brand	String	The manufacturer brand of this product. E.g. "Lenovo".
categoryId	List of Strings	The category IDs that this product belongs to.
categoryName	String	The category names that this product belongs to.
description	String	The product description.
id	String	The product ID. A unique identifier for this product.
name	String	The name of the product.
numReviews	Number	Total number of reviews for this product.
priceCents	Number	The regular price of this product.
rating	Number	The average product rating.
releaseDate	Date	The date this product was introduced into the catalog. This attribute allows us to calculate how "new" a product is.
salePriceCents	Number	The sale price of this product.

All other product attributes shared in the feed can be described by the name in the catalog feed that retailer shares with Algonomy.

Filter Query (fq)

Applies to: GET and POST Find calls
Format: Solr filter query syntax with special character encoding
Limitations:
- GET requests have a length limit; use POST for large fq values
- Maximum of 1000 boolean clauses in any Solr request

Key differences from filter parameter

The filter parameter allows basic filtering.
The fq parameter supports rich filtering with complex boolean logic, including nested AND/OR conditions.
Special characters must be encoded using a custom encoding scheme (see below).
For complex filters, prefer the POST method to avoid exceeding URL length limits.
Avoid excessive use of fq to maintain optimal API performance.
There is a limit of 1000 boolean clauses in any Solr request.

Special character encoding in fq

Because the fq parameter uses Solr syntax, field names with special characters (like spaces) must be encoded.

Encoding format: Same numeric code as URL encoding, but use $ instead of %
Example:
- Original field: Womens Sizes
- URL encoded: Womens%20Sizes
- fq encoded: Womens$20Sizes

Example usage

Basic fq clause:

Copy

fq=(Womens$20Sizes:"4")OR(Womens$20Sizes:"5.5")
fq=(Womens$20Sizes:%224%22)OR(Womens$20Sizes:%225.5%22)

Note: $20 (representing space) remains unchanged in the URL-encoded version of the fq value.

Date filtering with fq

When using the fq parameter for filtering date ranges, it's important to structure your query in a way that supports effective caching and avoids performance degradation.

Avoid the below pattern:

fq=date:[* TO NOW]

Why it's bad: NOW is evaluated down to the millisecond, making it a constantly changing value.
Consequence: This prevents caching and leads to inefficient query performance.
Workaround: If millisecond precision is truly needed, consider using cache=false.

Recommended patterns

Use rounded time units (like day or hour) for more efficient and cacheable queries.

fq=date:[* TO NOW/DAY+1DAY]

Good: Rounds NOW to the current day and adds one day.
Cache-friendly: Query changes only once per day.

fq=date:[* TO NOW/HOUR+1HOUR]

Good: Rounds NOW to the current hour and adds one hour.
Cache-friendly: Query updates hourly, ideal for most time-based use cases.

Note: Using NOW/DAY or NOW/HOUR ensures that your filters are more stable and efficiently cacheable, improving overall performance for frequently run queries.

Snapshot

Snapshot is a parameter that allows referencing a snapshot that is in Complete state (not yet activated) to verify results before activating the snapshot.

Note: Snapshot is only for clients using Streaming catalog.

searchConfig

searchConfig is a parameter which can be added to the Find request with the JSON config URL encoded as the value. This parameter is passed to the Solr search engine where the searchConfig can be overridden with a Find request by including the searchConfig HTTP parameter with a URL encode searchConfig JSON.

The Find request parameter format for any supported searchConfig key is:

Copy

&searchConfig.<keyName>=urlEncoded(jsonValue)

To override the searchConfig, replace the keyName with a required product attribute associated with the search:

Copy

&searchConfig=urlEncoded(fullSearchConfigJson)
 
For example:
&searchConfig.searchAttributeBoosts= urlEncoded(["excessInventory:LargeSize^0.25","excessInventory:MidSizer^0.0", excessInventory:SmallSize^0.0])

Find adds these values to the complementary searchConfig JSON set in the UI portal such that what is passed in query parameter always overrides what is set. For the same boost attribute:value pair, the request boost value will override the default configured boost value, so there will only be one boost for each attribute:value pair.

You can override the following single elements of search configurations that are configured in the Search Test Drive:

SearchAttributeBoosts
SearchAttributeFilters
psEnable (personalization)
synonymWeight

Use Cases

Following are the use cases for searchConfig parameter:

Use Case 1

No entry in siteConfig.searchConfig and valid entry in the Find API searchConfig

Site Configuration Portal (searchConfig)
Copy
```
{"psEnable":true, ... "ngramSearch":true}
```

Find API searchConfig

Copy

&searchConfig.searchAttributeBoosts=["size:US_8^0.25","size:US_7^0.33"]

Use Case 2

Valid entry of searchAttributeBoosts in siteConfig.searchConfig and valid entry in Find API searchConfig

Site Configuration Portal (searchConfig)

Copy

{"searchAttributeBoosts":["product_brand:Zalora^2.0"], ... , "ngramSearch":true}

Find API searchConfig

Copy

&searchConfig.searchAttributeBoosts=["size:US_8^0.25","size:US_7^0.33"]

Use Case 3

Valid entry of searchAttributeBoosts in siteConfig.searchConfig and invalid entry in Find API searchConfig

Site Configuration Portal (searchConfig)

Copy

{"searchAttributeBoosts":["product_brand:Zalora^2.0"], ... , "ngramSearch":true}

Find API searchConfig

Copy

&searchConfig.searchAttributeBoosts=["size:US_8^0.25","size:US_7^0.33"

Search Service Errors (If present)

Ignoring Invalid Search Config provided in the Search request
Copy
```
&searchConfig.searchAttributeBoosts=["size:US_8^0.25","size:US_7^0.33"
```

Use Case 4

Valid entry of searchAttributeBoosts in siteConfig.searchConfig and invalid field in Find API searchConfig

Site Configuration Portal (searchConfig)

Copy

{"searchAttributeBoosts":["product_brand:Zalora^2.0"], ... , "ngramSearch":true}

Find API searchConfig

Copy

&searchConfig.searchAttributeBoosts=["invalidField:abc^2"]

Search Service Errors (If present)

invalidField doesn't exist in schema from the boost query with value:
Copy
```
[invalidField:"abc"^2]
```

Use Case 5

String type searchConfig property

Site Configuration Portal (searchConfig)
Copy
```
{"mm":"50%", ... , "ngramSearch":true}
```
Find API searchConfig
Copy
```
&searchConfig.mm="100%"
```

Use Case 6

String type invalid searchConfig property

Site Configuration Portal (searchConfig)
Copy
```
{"mm":"50%", ... , "ngramSearch":true}
```
Site Configuration Portal (searchConfig)
Copy
```
&searchConfig.mm=100%
```
Search Service Errors (If present)

Ignoring Invalid searchConfig provided in the Search request:
Copy
```
&searchConfig.mm=100%
```

Use Case 7

Integer type searchConfig property

Site Configuration Portal (searchConfig)
Copy
```
{"psditem":25, ... , "ngramSearch":true}
```
Find API searchConfig
Copy
```
&searchConfig.psdItem=10
```

Use Case 8

Double type searchConfig property

Site Configuration Portal (searchConfig)
Copy
```
{"psdMaxS":0.9, ... , "ngramSearch":true}
```
Find API searchConfig
Copy
```
&searchConfig.psdMaxS=0.5
```

Use Case 9

JSON object type searchConfig property

Site Configuration Portal (searchConfig)

Copy

{"offMenu":{"offMenuFlagField":"onlySearchableByArticleNumber",

"offMenuSearchField":"articleNumber","offMenuDefault":"exclude"}

,..,"ngramSearch":true

Find API searchConfig

Copy

&searchConfig.offMenu={"offMenuFlagField":"onlySearchableByArticleNumber",

"offMenuSearchField":"articleNumber","offMenuDefault":"include"}

Use Case 10

Boolean type searchConfig property

Site Configuration Portal (searchConfig)
Copy
```
{"psditem":25, ... , "ngramSearch":true}
```
Find API searchConfig
Copy
```
&searchConfig.ngramSearch=false
```

Use Case 11

Combination of various searchConfig property

Site Configuration Portal (searchConfig)

Copy

{"psEnable":true,"psdItem":25,"psdMinS":0.0,"psdMaxS":0.9,
"pBal":4.0,"enableMetrics":true,"emw":10.0,"synonymWeight":0.9,
"ngramSearch":false,"tie":0.5,"vbp":1.9,"pbp":1.9,"rufws":true,
"searchAttributeBoosts":["product_brand:ZALORA^2.0"]}

Find API searchConfig

Copy

&searchConfig.searchAttributeBoosts=["product_effectiveprice_cents:5000^100"
,"product_brand:ZALORA^5","InvalidField:abc^2"]
&searchConfig.searchAttributeFilters=["product_effectiveprice_cents:500"]
&searchConfig.ngramSearch=true
&searchConfig.synonymWeight=1.1

Search Service Errors (If present)

invalidField doesn't exist in schema from the boost query with value:
Copy
```
[invalidField:"abc"^2]
```

searchAttributeBoosts

searchAttributeBoosts is a keyName passed to the Solr where it recomputes the output to boost the search results. It specifies the search attribute name, value, and amount of boost in the following format "<search-attribute-name>:<value>^<boost-amount>".

For example, search-attribute-name is 'excessInventory', value is 'LargeSize', and boost-amount is '0.25'.

Copy

&searchConfig.searchAttributeBoosts= urlEncoded("excessInventory:LargeSize^0.25")

A positive boost value increases the weight of the product with that attribute:value combination and a negative boost value moves the product to the end of the search results list.

searchAttributeFilters

Copy

searchConfig.searchAttributeFilters=urlEncoded(["product_effectiveprice_cents:500"])

psEnable

Copy

psEnablesearchConfig.psEnable=false

synonymWeight

Copy

synonymWeightsearchConfig.synonymWeight=1.1

ngramSearch

N-grams are like a sliding window that moves across a word, a continuous sequence of characters of a specified length which in Find is defaulted to 1. ngramSearch is often used with autocomplete or type-ahead feature. For example, a shopper types each character in the search box, there is a match based on the characters entered. Some Find customers use the Find API for auto-complete of products instead of the autocomplete API. It is important for them to be able to set ngramSearch=true as part of the Find query. It is recommended to set it to ngram=false for general product queries.

There can be a system-wide setting for ngramSearch in the site configuration which an Algonomy consultant sets up. If it is not set up in the site configuration, the default is true. This parameter will override the settings in the site configuration as well as the default value.

Copy

ngramSearch=true/false

edgeNgramSearchable

edgeNgramSearchable is a property definition setting for streaming clients to restrict ngram token generation on specific fields. It works on the logic of existing ngramSearch.

Allows partial matching on this field (min:1).
Matches only on prefix characters.
“ABC” will match the field with ABC123DEF but “123" will NOT match.

ngramSearchable

Allows substring matching.
In any part of a word (min:3 and max:20 characters).
For example, “123” will match the field with ABC123DEF.

Note: To use ngramsearch property configurations instead of the “sitewide” ngramSearch, this needs to be enabled with the assistance of your Algonomy consultant or support team.

Minimum Match (mm)

Minimum match indicates the minimum number of terms that must match. The specification strings contain the following formats and the valid values for minimum match with an example parameter in Solr:

Positive integer 3: It indicates a fixed value regardless of the number of optional clauses.
Negative integer -2: It indicates the total number of optional clauses, minus this number should be mandatory.
Percentage 75%: It indicates the necessary percentage of the total number of optional clauses. The number computed from the percentage is rounded down and used as the minimum.
Negative percentage -25%: It indicates missing percentage of the total number of optional clauses. The number computed from the percentage is rounded down, before being subtracted from the total to determine the minimum.
An expression 3<90%: A positive integer, followed by the less-than symbol, followed by any of the previously mentioned specifiers is a conditional specification. It indicates that, if the number of optional clauses is equal to (or less than) the integer, they are all required, but if it is greater than the integer, the specification applies. In this example: if there are 1 to 3 clauses, they are all required, but for 4 or more clauses only 90% are required.
Multiple conditional expressions involving > or < signs 2<-25% 9<-3: Multiple conditional specifications can be separated by spaces, each one only being valid for numbers greater than the one before it. In this example: if there are 1 or 2 clauses both are required, if there are 3-9 clauses all but 25% are required, and if there are more than 9 clauses, all but three are required.

For more information see:

Copy

https://lucene.apache.org/solr/guide/6_6/the-dismax-query-parser.html#TheDisMaxQueryParser-Themm_MinimumShouldMatch_Parameter)

Date Filtering and Searching

Find implemented with a date field where customers can use this custom date field for the product to perform the date range queries against the custom field. This feature helps customer to indicate about the product visibility in the Solr collection. Some customers may need date math operations to be supported for their Find queries to fit their use cases which may include sorting by release data, filtering the new products, warranty period, etc. The date field is an opt-in feature. Please contact your Algonomy cust omer support to get this feature enabled if required.

Note: If you are using streaming API, you must create a new snapshot after the site configuration has been enabled.

Use Cases

Following are the different use cases where a date field is added as a new data type for different scenarios:

Use Case 1

last_modified field indexed in catalog item type when enableDateIndexing is on.

Example Request

last_modified is a system defined field that value is ingest timestamp in the date format.
Copy
```
rrserver/api/find/v1/c17a665223e4708f?start=0&rows=50& placement=search_page.find&lang=en &query=*
```

Example Response

Copy

{
...
    "docs": [ {
        "id": "BASIC-Prod-1",
        "id": "BASIC-Prod-2"
    }]
...
}

Use Case 2

product_sale_expiry_date (custom date) field with filter customer sends timestamp.

Example Request

Copy

rrserver/api/find/v1/c17a665223e4708f?start=0&rows=50& placement=search_page.find&lang=en &query=*&fq=publish_date:[2022-05-07T07:57:51.991ZTONOW-11DAY]

Example Response

Copy

{
...
    "docs": [ {
        "id": "BASIC-Prod-2"    }]
...
}

Use Case 3

product_release_date (custom date) field with filter (ENG-21544) - client sends date time

Example Request

Copy

rrserver/api/find/v1/c17a665223e4708f?start=0&rows=50& placement=search_page.find&lang=en &query=*&fq=publish_date:[2022-02-07T07:57:51.991ZTO2022-02-20T07:57:51.991Z]

Example Response

Copy

{
...
    "docs": [ {
        "id": "BASIC-Prod-3"    }]
...
}