Personalized Site Search Queries

when a customer executes a search, or query, it triggers a personalized site search request to identify complete records from your entire storefront that meet the query criteria the response includes multiple records, representing the search results based on the request configuration, each returned record contains data related to a single product, a product category merchandising page /#category page records and personalized category page queries , or a piece of content published on your site /#returning content page records if you've implemented the monetate javascript api https //developer monetate com/js api , you can contact your dedicated customer success manager (csm) to request that custom personalized search results and personalized search suggestions action templates be added to your account so that you can deploy auto suggestions and site search to your site using a web experience instead of your own calls to the personalized search api refer to create a personalized site search experience https //docs monetate com/docs/create personalized site search experience for more information refer to omnichannel personalized search action request docid\ xzjy8ycndlmwjle 2oxmw for the information you must provide in an engine api request for an omnichannel experience configured with an omnichannel personalized search action https //docs monetate com/docs/configure omnichannel personalized search action { "name" "personalized site search query request", "method" "post", "url" "https //engine monetate net/api/search/v1/site search/{name}/{instance}/{domain}/search", "description" "", "tab" "examples", "examples" { "languages" \[ { "id" "t g5uw vjfdkhgc0 8sau", "language" "json", "code" "{\n \\"searchtoken\\" \\"monetate 156925593843210765\\",\n \\"recordqueries\\" \[\n {\n \\"id\\" \\"productsearch\\",\n \\"typeofrequest\\" \\"search\\",\n \\"settings\\" {\n \\"query\\" {\n \\"term\\" \\"short\\"\n },\n \\"limit\\" 5,\n \\"typeofrecords\\" \[\n \\"monetate product\\"\n ],\n \\"fields\\" \[\n \\"id\\",\n \\"name\\",\n \\"price\\"\n ]\n }\n }\n ]\n}", "customlabel" "example personalized site search query request" } ], "selectedlanguageid" "t g5uw vjfdkhgc0 8sau" }, "results" { "languages" \[ { "id" "m5iyl778adwtdmd1ku7o ", "language" "200", "customlabel" "", "code" "{\n \\"queryresults\\" \[\n {\n \\"id\\" \\"productsearch\\",\n \\"meta\\" {\n \\"qtime\\" 6,\n \\"noofresults\\" 5,\n \\"totalresultsfound\\" 104,\n \\"typeofsearch\\" \\"wildcard and\\",\n \\"offset\\" 0,\n \\"debugginginformation\\" {},\n \\"notificationcode\\" 1,\n \\"searchedterm\\" \\"short\\",\n \\"searchtoken\\" \\"monetate 156925593843210765\\",\n \\"ispersonalised\\" false\n },\n \\"records\\" \[\n {\n \\"price\\" \\"45 00\\",\n \\"id\\" \\"31366431146046\\",\n \\"name\\" \\"erika running short\\"\n \\"searchclicktoken\\" \\"monetate nlisc2lje2njixe3dumynze3mjexoycd\\"\n },\n {\n additional records \n }\n ]\n }\n ]\n}" } ], "selectedlanguageid" "m5iyl778adwtdmd1ku7o " }, "request" { "pathparameters" \[ { "name" "name", "kind" "required", "type" "string", "description" "the client's account (for example, \\"a 1db61f7a\\") as it appears in the value of channel used in the engine api request to obtain the search token ", "" "the client's account (for example, \\"a 1db61f7a\\") as it appears in the value of channel used in the engine api request to obtain the search token " }, { "name" "instance", "kind" "required", "type" "string", "description" "the client's account environment the value must either be \\"p\\" for production or \\"d\\" for development ", "" "the client's account environment the value must either be \\"p\\" for production or \\"d\\" for development " }, { "name" "domain", "kind" "required", "type" "string", "description" "the client's domain (for example, \\"product monetate me\\") as it appears in the value of channel used in the engine api request to obtain the search token ", "" "the client's domain (for example, \\"product monetate me\\") as it appears in the value of channel used in the engine api request to obtain the search token " } ], "queryparameters" \[], "headerparameters" \[ { "name" "content type", "kind" "required", "type" "string", "description" "the value must be \\"application/json \\"", "" "the value must be \\"application/json \\"" } ], "bodydataparameters" \[ { "name" "searchtoken", "kind" "required", "type" "string", "description" "a token used to authenticate the search request obtained by sending a request to the engine api see \\"obtaining a search token\\" in \\"calling the personalized search api\\" for more information ", "" "a token used to authenticate the search request obtained by sending a request to the engine api see \\"obtaining a search token\\" in \\"calling the personalized search api\\" for more information " }, { "name" "recordqueries", "kind" "required", "type" "object", "description" "the set of parameters that define a personalized site search request ", "children" \[ { "name" "boost", "kind" "optional", "type" "object", "description" "query level aspects to influence the relevancy rankings refer to \\"boosting and burying results at run time\\" for more information ", "children" \[ { "name" "filters", "kind" "optional", "type" "object", "description" "the specific attribute and values that you want personalized search to boost or bury in the search results ", "children" \[ { "name" "key", "kind" "optional", "type" "string", "description" "the unique identifier of the attribute that you want personalized search to boost or bury " }, { "name" "values", "kind" "optional", "type" "array", "description" "one or more values of an attribute that you want personalized search to boost or bury " }, { "name" "weight", "kind" "optional", "type" "number", "description" "a numeral representing how much you want personalized search to boost or bury the records matching the other key value pairs in the filters object for each product you can boost the score up to 999, or lower it anywhere from –1 to –999 a score greater than 1 boosts the product in search results, causing it to appear higher a negative score buries the product, causing it to appear lower " } ] } ] }, { "name" "id", "kind" "required", "type" "string", "description" "the unique identifier associated with the request " }, { "name" "typeofrequest", "kind" "required", "type" "string", "description" "the type of query request use \\"search\\" for the value " }, { "name" "settings", "kind" "required", "type" "object", "description" "the set of key value pairs that define the settings used for search results ", "children" \[ { "name" "query", "kind" "required", "type" "object", "description" "the set of key value pairs that define the search term the customer input ", "children" \[ { "name" "term", "kind" "required", "type" "string", "description" "the search term the customer input " } ] }, { "name" "fields", "kind" "optional", "type" "array", "description" "the collection of product catalog attribute values that you want retrieved (for example, id, name, price) refer to \\"using the fields array\\" for more information " }, { "name" "typeofsearch", "kind" "optional", "type" "string", "description" "the method that personalized search uses to find matches for a customer's search term refer to \\"specifying a search method\\" for possible values " }, { "name" "limit", "kind" "optional", "type" "number", "description" "the number of records you want displayed per results page if you don't pass this key in the request, then personalized search uses the default value of 12 \n\nyou can fetch a maximum of 100 records when you pass the limit key to get more than 100 records, you must define the fields array in the request call " }, { "name" "typeofrecords", "kind" "required", "type" "array", "description" "the type of results to return use \\"monetate product\\" for the value when you want personalized search to return products when you want personalized search to return content published on your site, use \\"monetate cms\\", \\"monetate category\\", or a custom value of the category attribute passed in a mapped content pages dataset refer to \\"returning content page records\\" for more information " }, { "name" "sort", "kind" "optional", "type" "string", "description" "the method by which the results are ordered refer to \\"sorting results\\" for the possible values " }, { "name" "fallbackqueryid", "kind" "optional", "type" "string", "description" "the id of another query to be fired if the current query yields too few results refer to \\"including fallback queries\\" for more information " }, { "name" "fallbackwhencountlessthan", "kind" "optional", "type" "integer", "description" "the minimum number of results that the initial query must return to prevent the fallback query from returning its own results refer to \\"including fallback queries\\" for more information " } ] }, { "name" "isfallbackquery", "kind" "optional", "type" "boolean", "description" "used only with the fallback query refer to \\"including fallback queries\\" for more information \n\nif set to true, then personalized search triggers the fallback query only when the initial query fails to return enough results to meet the value of fallbackwhencountlessthan \n\nif set to false, then personalized search triggers the fallback query even when the initial query returns enough results to meet or exceed the value of fallbackwhencountlessthan the default value is false " } ], "schema" \[ { "name" "boost", "kind" "optional", "type" "object", "description" "query level aspects to influence the relevancy rankings refer to \\"boosting and burying results at run time\\" for more information ", "children" \[ { "name" "filters", "kind" "optional", "type" "object", "description" "the specific attribute and values that you want personalized search to boost or bury in the search results ", "children" \[ { "name" "key", "kind" "optional", "type" "string", "description" "the unique identifier of the attribute that you want personalized search to boost or bury " }, { "name" "values", "kind" "optional", "type" "array", "description" "one or more values of an attribute that you want personalized search to boost or bury " }, { "name" "weight", "kind" "optional", "type" "number", "description" "a numeral representing how much you want personalized search to boost or bury the records matching the other key value pairs in the filters object for each product you can boost the score up to 999, or lower it anywhere from –1 to –999 a score greater than 1 boosts the product in search results, causing it to appear higher a negative score buries the product, causing it to appear lower " } ] } ] }, { "name" "id", "kind" "required", "type" "string", "description" "the unique identifier associated with the request " }, { "name" "typeofrequest", "kind" "required", "type" "string", "description" "the type of query request use \\"search\\" for the value " }, { "name" "settings", "kind" "required", "type" "object", "description" "the set of key value pairs that define the settings used for search results ", "children" \[ { "name" "query", "kind" "required", "type" "object", "description" "the set of key value pairs that define the search term the customer input ", "children" \[ { "name" "term", "kind" "required", "type" "string", "description" "the search term the customer input " } ] }, { "name" "fields", "kind" "optional", "type" "array", "description" "the collection of product catalog attribute values that you want retrieved (for example, id, name, price) refer to \\"using the fields array\\" for more information " }, { "name" "typeofsearch", "kind" "optional", "type" "string", "description" "the method that personalized search uses to find matches for a customer's search term refer to \\"specifying a search method\\" for possible values " }, { "name" "limit", "kind" "optional", "type" "number", "description" "the number of records you want displayed per results page if you don't pass this key in the request, then personalized search uses the default value of 12 \n\nyou can fetch a maximum of 100 records when you pass the limit key to get more than 100 records, you must define the fields array in the request call " }, { "name" "typeofrecords", "kind" "required", "type" "array", "description" "the type of results to return use \\"monetate product\\" for the value when you want personalized search to return products when you want personalized search to return content published on your site, use \\"monetate cms\\", \\"monetate category\\", or a custom value of the category attribute passed in a mapped content pages dataset refer to \\"returning content page records\\" for more information " }, { "name" "sort", "kind" "optional", "type" "string", "description" "the method by which the results are ordered refer to \\"sorting results\\" for the possible values " }, { "name" "fallbackqueryid", "kind" "optional", "type" "string", "description" "the id of another query to be fired if the current query yields too few results refer to \\"including fallback queries\\" for more information " }, { "name" "fallbackwhencountlessthan", "kind" "optional", "type" "integer", "description" "the minimum number of results that the initial query must return to prevent the fallback query from returning its own results refer to \\"including fallback queries\\" for more information " } ] }, { "name" "isfallbackquery", "kind" "optional", "type" "boolean", "description" "used only with the fallback query refer to \\"including fallback queries\\" for more information \n\nif set to true, then personalized search triggers the fallback query only when the initial query fails to return enough results to meet the value of fallbackwhencountlessthan \n\nif set to false, then personalized search triggers the fallback query even when the initial query returns enough results to meet or exceed the value of fallbackwhencountlessthan the default value is false " } ] } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "response" \[ { "name" "id", "kind" "optional", "type" "string", "description" "the id of the record query for which the results are being returned " }, { "name" "meta", "kind" "optional", "type" "object", "description" "the query related parameters ", "children" \[ { "name" "qtime", "kind" "optional", "type" "number", "description" "the time personalized search took to fetch the response " }, { "name" "noofresults", "kind" "optional", "type" "number", "description" "the number of results requested to be returned for the query " }, { "name" "totalresultsfound", "kind" "optional", "type" "number", "description" "the total results found for the query " }, { "name" "typeofsearch", "kind" "optional", "type" "string", "description" "the search method(s) that personalized search used to retrieve the results refer to \\"specifying a search method\\" in this documentation for more information " }, { "name" "offset", "kind" "optional", "type" "string", "description" "the index of the first result returned in the response " }, { "name" "debugginginformation", "kind" "optional", "type" "string", "description" "information that can be useful for debugging the query (for example, the actual query that personalized search fired, including any synonyms or de compounded words taken into consideration) " }, { "name" "notificationcode", "kind" "optional", "type" "number", "description" "a code indicating if any actions were taken on the record possible values are as follows \n\n1 — nothing to report \n2 — the price of the record is using the base currency " }, { "name" "searchedterm", "kind" "optional", "type" "string", "description" "the customer's search term submitted for the query " }, { "name" "searchtoken", "kind" "optional", "type" "string", "description" "the token returned by the decision request to the engine api sent on page load that contains the relevant information for the experience " }, { "name" "ispersonalized", "kind" "optional", "type" "boolean", "description" "whether or not customer context was applied to the results " } ] }, { "name" "records", "kind" "optional", "type" "object", "description" "the records matching the query each record object is a map of key value pairs, where the key is the name of an attribute (for example, id, name, price) and its value in the mapped product catalog ", "children" \[ { "name" "id", "kind" "optional", "type" "string", "description" "the unique identifier of the record within personalized search " }, { "name" "itemgroupid", "kind" "optional", "type" "string", "description" "the identifier for a group of products that come in different versions as set in the value of the item group id attribute in the mapped product catalog " }, { "name" "name", "kind" "optional", "type" "string", "description" "the name of the record (for example, the product name or category title) " }, { "name" "url", "kind" "optional", "type" "string", "description" "the fully qualified url the customer used to access the record on your site " }, { "name" "sku", "kind" "optional", "type" "string", "description" "a product's unique identifier as set in the value of the id attribute in the mapped product catalog " }, { "name" "instock", "kind" "optional", "type" "string", "description" "whether or not the product is in stock the value is either \\"yes\\" or \\"no \\"" }, { "name" "price", "kind" "optional", "type" "number", "description" "the original price of the product, before any discounts as set in the value of the price attribute in the mapped product catalog \n\nyou can use this parameter as a \\"was \[price]\\" when used with saleprice " }, { "name" "saleprice", "kind" "optional", "type" "number", "description" "the actual selling price of ther product, or the \\"now \[price]\\" when used with price when using filters, the sale price is represented by monetate price " }, { "name" "startprice", "kind" "optional", "type" "number", "description" "the value of saleprice for the variant with the lowest price among all variants with the same item group id you can use this key value pair for an \\"as low as\\" price " }, { "name" "toprice", "kind" "optional", "type" "number", "description" "the value of saleprice for the variant with the highest price among all variants with the same item group id you can use this key value pair for a \\"from x to y\\" price range " }, { "name" "groupprices", "kind" "optional", "type" "number", "description" "the prices of a record in format groupid\ price so that you can use your own front end logic to display prices in real time this field isn't always populated, in part because price and saleprice are automatically calculated, so there's no need to use this key value pair in most cases " }, { "name" "currency", "kind" "optional", "type" "string", "description" "the currency code applicable to the price values being displayed " }, { "name" "category", "kind" "optional", "type" "string", "description" "a list of a record's most specific categories that excludes the full path, with double semicolons (;;) used to separate them (for example, a record in both mens > shoes and mens > tees has a value of \\"shoes;;tees\\") " }, { "name" "shortdesc", "kind" "optional", "type" "string", "description" "the short description of the record as set in the value of the description attribute in the mapped product catalog " }, { "name" "rating", "kind" "optional", "type" "number", "description" "the product's rating between 0 and 5 " }, { "name" "ratingcount", "kind" "optional", "type" "number", "description" "the number of ratings customers have given the product " }, { "name" "image", "kind" "optional", "type" "string", "description" "the fully qualified url to the record's main image " }, { "name" "imagehover", "kind" "optional", "type" "string", "description" "the fully qualified url to the record's secondary image " }, { "name" "totalvariants", "kind" "optional", "type" "number", "description" "the number of variants available for a product in addition to the variant in the search results (for example, a product included in the results for a customer's \\"small tshirt\\" search has 3 color variants available in size small, so the value of totalvariants is 2; a search for \\"tshirt\\" would include the same product, but the value of totalvariants is 8 because the product comes in 3 colors, each in 3 sizes) " }, { "name" "monetate manual boosting", "kind" "optional", "type" "number", "description" "the rule based merchandising score (rms) you set on the rule based merchandising tab of the promotions page of the personalized search user interface " }, { "name" "monetate product boosting", "kind" "optional", "type" "number", "description" "the product level score (pls) you set on the product level boosting tab of the promotions page of the personalized search user interface " }, { "name" "monetate category", "kind" "optional", "type" "string", "description" "the record's categorization within personalized search, with the product name separated from its category hierarchy with double semicolons (;;) and then the category hierarchy itself separated by single semicolons (for example, \\"mybrand tent;;sporting goods;outdoor recreation;camping;tents\\")" }, { "name" "brand", "kind" "optional", "type" "string", "description" "the product's brand as set in the value of the brand attribute in the mapped product catalog " }, { "name" "typeofrecord", "kind" "optional", "type" "string", "description" "the record's type (for example, \\"monetate product\\")" }, { "name" "additionaldatatoreturn", "kind" "optional", "type" "string", "description" "if present for the record, you can use the data to display attribute variations in one product entry on the search results page refer to \\"displaying product variants\\" in \\"preparing to implement personalized search\\" in the monetate knowledge base for more information " }, { "name" "searchclicktoken", "kind" "optional", "type" "string", "description" "a token that contains the relevant information about the customer, about the omnichannel personalized search experience, and about the record the customer clicked " } ] } ], "hastryitout" false } using the fields array by default, records returned in the response include values for all attributes in the mapped product catalog, including custom attributes https //docs monetate com/docs/preparing to implement personalized search#selecting a product catalog use the fields array to limit the response to the specific attribute values you want returned doing so improves response time and decreases response size as such, you should limit returned attribute values to only those you intend to render before you can include one or more custom attributes in the fields array of a request, you must first contact your dedicated csm so that monetate can enable this option specifying a search method the value that you can pass in the optional typeofsearch key determines the method(s) that personalized search uses to find record matches for a customer's search term the value options for typeofsearch are as follows value description default this value prompts monetate to use a successive order of search methods to find matches the first method attempted is and, which means that monetate must find all the words of a search term exactly as typed in a record to include it in the results if it finds no results, monetate then tries the wildcard and search method the order of search method s used is as follows and wildcard and fuzzy and wildcard or fuzzy or if a search term only contains 1 word or more than 6 words, then monetate skips the wildcard or and fuzzy or search method s wildcard and this value dictates that all words of the search term must be found somewhere in a record for monetate to include it in the results to bolster the possibility of matches, monetate appends a wildcard suffix to the last word of the search term (for example, the search term hooded jacket becomes hooded jacket , and monetate then looks for records containing hooded and any words beginning with jacket) fuzzy and this value indicates a search method that is the same as the wildcard and query but with a certain amount of fuzziness, or approximate string matching, to account for spelling mistakes (for example, using this query type, monetate can still match the search term hooder jakcet to records containing hooded and jacket ) wildcard or this value indicates an or search method , so monetate must find at least 1 of the search term words in a record to bolster the possibility of matches, monetate appends a wildcard suffix to the last word of the search term (for example, the search term hooded jacket becomes hooded jacket , and monetate then looks for records containing hooded or any words beginning with jacket ) fuzzy or this value indicates a search method that is the same as the wildcard or search method but with a certain amount of fuzziness, or approximate string matching, to account for spelling mistakes (for example, using this search method , monetate can still match the search term hooder jakcet to records containing hooded or jacket ) and this value indicates that monetate must find all the words of a search term exactly as typed in a record to include it in the results (for example, with this search method , a search for hooded jacket only yields records that contain hooded and jacket ) or this value indicates that monetate must find at least 1 of the words of a search term exactly as typed in a record to include it in the results (for example, with this search method , a search for hooded jacket yields records that contain hooded or jacket or hooded jacket ) here's an example query request with the fuzzy or search method specified in the typeofsearch key value pair, along with the response example query request with search method specified { "searchtoken" "monetate 156925593843210765", "recordqueries" \[ { "id" "productsearch", "typeofrequest" "search", "settings" { "typeofsearch" "fuzzy and", "query" { "term" "hooder jakcet" }, "limit" 5, "typeofrecords" \[ "monetate product" ], "fields" \[ "id", "name", "price" ] } } ] } response { "queryresults" \[ { "id" "productsearch", "meta" { "qtime" 6, "noofresults" 5, "totalresultsfound" 104, "typeofsearch" "fuzzy and", "offset" 0, "debugginginformation" {}, "notificationcode" 1, "searchedterm" "hooder jakcet", "searchtoken" "monetate 156925593843210765", "ispersonalised" false }, "records" \[ { "price" "95 00", "id" "31366431146046", "name" "mybrand hooded jacket" "searchclicktoken" "monetate nirsc2lje2njixt3aumynze3mjextyjd" }, { additional records } ] } ] } including fallback queries while you can present a customer with a "no results found" message when their search term yields no products or other results, you can configure a query request docid\ gwgtooic olmkssgmarow that includes a backup that presents the customer with the results from another query that might interest them not only does a fallback query present the customer with results in lieu of a "no results found" message, it doesn't require additional http requests furthermore, the fallback query doesn't jeopardize the initial query's performance to include a fallback query in a request, add the fallbackqueryid key to the initial search query, and use its value to identify the fallback in a second query in the same request, pass the id key with the same value as the value of the fallbackqueryid key, the boolean key isfallbackquery with the value true , along with the other required key value pairs and any optional key value pairs you can add the fallbackqueryid key value pair only to the initial search query you cannot add a fallback query to a fallback query personalized search triggers the fallback query only when the initial query fails to return the minimum number of results, which you define using the fallbackwhencountlessthan key value pair for example, if you want the fallback query to supply results only if the initial query yields fewer than two results, then pass "fallbackwhencountlessthan" 3 in the initial query if the value of isfallbackquery is false , then personalized search triggers the fallback query even when the initial query returns enough results to meet or exceed the value of fallbackwhencountlessthan the results of the fallback query are added to those from the initial query, which could potentially double the number of results the default value of isfallbackquery is false here's an example of a personalized site search request that includes a fallback query along with its response example query request with fallback { "searchtoken" "monetate 156925593843210757", "recordqueries" \[ { "id" "productlist", "typeofrequest" "search", "settings" { "query" { "term" "pickleball shorts" }, "typeofsearch" "fuzzy or", "limit" 5, "typeofrecords" \[ "monetate product" ] "sort" "relevance", "fallbackqueryid" "productlistfallback", "fallbackwhencountlessthan" 3 "fields" \[ "id", "name", "price" ] } }, { "id" "productlistfallback", "typeofrequest" "search", "isfallbackquery" "true", "settings" { "query" { "term" "short" }, "typeofsearch" "and", "limit" 5, "typeofrecords" \[ "monetate product" ] "sort" "relevance", "fields" \[ "id", "name", "price" ] } } ] } response { "queryresults" \[ { "id" "productlist", "meta" { "qtime" 1386, "noofresults" 5, "totalresultsfound" 0, "typeofsearch" "fuzzy or", "debugginginformation" {}, "notificationcode" 1, "searchedterm" "pickleball shorts", "searchtoken" "monetate 156925593843210757", "ispersonalised" false }, "records" \[] }, { "id" "productlistfallback", "meta" { "qtime" 169, "noofresults" 5, "totalresultsfound" 104, "typeofsearch" "and", "debugginginformation" {}, "notificationcode" 1, "searchedterm" "short", "searchtoken" "monetate 156925593843210757", "ispersonalised" false }, "records" \[ { "id" "31366431146046", "name" "erika running short" "price" "45 00", "searchclicktoken" "monetate niisc2lje2njixe3aumcnze3mjexiycd" }, { additional records } ] } ] } sorting results by default, records are sorted by relevance to the search term you can specify another order by including the sort key value pair in the settings object example query request with sorting { "searchtoken" "monetate 156925593843210765", "recordqueries" \[ { "id" "productsearch", "typeofrequest" "search", "settings" { "query" { "term" "short" }, "limit" 5, "sort" "price asc" "typeofrecords" \[ "monetate product" ] } } ] } the value options for sort are as follows value description relevance the default sort order, with sorting based on a combination of personalized search's machine learning and your merchandising configurations price asc sort by the value of saleprice in each record (the value of the sale price attribute in the mapped product catalog) in ascending order, or by the value of price if the mapped product catalog doesn't include a sale price price desc sort by the value of saleprice in each record (the value of the sale price attribute in the mapped product catalog) in descending order , or by the value of price if the mapped product catalog doesn't include a sale price name asc sort by the value of name in alphabetical order name desc sort by the value of name in reverse alphabetical order rating asc sort by the average rating for each result in ascending order, if the mapped product catalog includes rating information rating desc sort by the average rating for each result in descending order, if the mapped product catalog includes rating information new arrival asc sort by the date each record was published in ascending order new arrival desc sort by the date each record was published in descending order setting up pagination a page of search results contains a number of records up to the limit key value pair specified in the settings object additional pages containing records beyond that limit can be created by repeating the query request with the offset key value pair example query request with offset { "searchtoken" "monetate 156925593843210765", "recordqueries" \[ { "id" "productsearch", "typeofrequest" "search", "settings" { "query" { "term" "short" }, "limit" 5, "offset" 5, "typeofrecords" \[ "monetate product" ] } } ] } the value of the offset key indicates how many records should be skipped in this example, the returned records are the sixth through tenth matches to properly paginate the search results, repeat the request while incrementing the offset in multiple values of the limit for example, if the limit is 5 , then the offsets in the sequence of requests should be 0 , 5 , 10 , 15 , 20 , and so on boosting and burying results at run time in addition to the product level boosting scores https //docs monetate com/docs/personalized search boost bury#product level boosting scores and rule based merchandising scores https //docs monetate com/docs/personalized search boost bury#rule based merchandising scores that you can set in the personalized search user interface to influence search results, you can also boost and bury product records that have a specific product catalog attribute value in the request that you send to personalized search for example, a retailer wants to boost products in the search results that are available at a customer's preferred store location as indicated by a store id the client passes this information to monetate in the instockstores custom attribute in its mapped product catalog therefore, the request must reference that custom attribute along with store id values as well as a numeric weight that indicates how much to boost the products with one of the store ids in the response prerequisites before you can send a personalized search api request that includes parameters to boost or bury product records, you must ensure the following about the product catalog attribute(s) that you plan to use for the boosting or burying monetate has enabled the attribute to serve as a facet the attribute has been disabled as a search results filter option on the facets tab of the personalized search customizations page refer to search results customizations https //docs monetate com/docs/personalized search customizations#customizing facets in the monetate knowledge base for more information about viewing enabled attributes and disabling them as facets in some use cases, you may need to ensure that the attribute's data type is defined in the product catalog schema as multi string , which was set when the schema was first created in the monetate platform when the user selected comma separated string in step 4 of the create dataset schema wizard https //docs monetate com/docs/create a product catalog dataset schema you can verify the data type on the attributes tab of the mapped product catalog's details page in the monetate platform callout of the data type column of the table on the attributes tab of a product catalog dataset's details page in the monetate platform in the example of the retailer wanting to boost products available at a customer's preferred location, the client must ensure that the data type for the storestock custom attribute is multi string so that personalized search can parse the specific store id values in the response and then filter and boost as the client defined in the request defining the run time boost or bury rule add the boost object to a site search query request to identify not only the attribute and its value(s) on which you want to base the boost or bury run time rule but also how much you want the matching records boosted or buried in the results the weight key value pair identifies the impact you want the rule to have on the matching records the value must be a decimal between zero and 999 a value greater than 1 boosts the records within the rankings, and a value of zero to 1 buries the records within the rankings the boost object must appear before the other record querying parameters in the request furthermore, you cannot use a negative number as the value of the weight key value pair example site search query request with boosting { "recordqueries" \[ { "boost" { "filters" \[ { "key" "instockstores", "values" \[ "190" ], "weight" 900 } ] }, "id" "productsearch", "typeofrequest" "search", "settings" { "query" { "term" "shirt" }, "limit" 20, "typeofrecords" \[ "monetate product" ], "fields" \[ "id", "name", "instock", "instockstores" ] } } ], "suggestions" \[], "searchtoken" "6 18 ejxdjreogjaurf" } keep in mind that including the boost object in a request doesn’t guarantee that product records that match its filters criteria are boosted to the very top or buried at the bottom of search results as indicated by the value of weight in all search queries returning content page records to return records for product category merchandising pages and supplemental ecommerce content pages in site search results, you must first create the necessary content pages datasets https //docs monetate com/docs/content pages datasets in the monetate platform and associate each one with the mapped product catalog dataset if you've uploaded one or more content pages datasets to monetate and associated each one to the product catalog mapped for use in personalized search, then you can return in search results the records for supplemental ecommerce content published on your site—such as blog posts, buying guides, owner's manuals, specific category merchandising pages, and other media—alongside product records refer to the content pages datasets https //docs monetate com/docs/content pages datasets documentation in the monetate knowledge base for the dataset specification and the steps for creating and updating a content pages dataset any value that you pass in the typeofrecords array for content records is derived from the value of the category attribute in each content pages dataset associated with the mapped product catalog https //docs monetate com/docs/edit associated product catalogs that value can be a standard value— monetate cms for any page that isn't a product detail page or product category page, and monetate category for a unique product category page—or a custom value used in the dataset a custom value begins with an underscore character ( ) when using a custom category attribute value from a mapped content pages dataset in the typeofrecords array, you must ensure that the letter case matches the letter case of the value as it appears in the dataset for example, a retailer established video as a custom value for its site's library of product demo videos so that personalized search can examine those video records for matches for a customer's search query, the retailer passes video in the typeofrecords array in the site search request here's an example of a personalized site search request configured to search records for unique category pages, along with its response example site search query request for category content page records { "searchtoken" "monetate 156925593843210765", "recordqueries" \[ { "id" "categorysearch", "typeofrequest" "search", "settings" { "typeofsearch" "wildcard and", "query" { "term" "tops" }, "limit" 5, "typeofrecords" \[ "monetate category" ], "fields" \[ "id", "name", "description" ] } } ] } response { "queryresults" \[ { "id" "categorysearch", "meta" { "qtime" 6, "noofresults" 5, "totalresultsfound" 104, "typeofsearch" "wildcard and", "offset" 0, "debugginginformation" {}, "notificationcode" 1, "searchedterm" "tops", "searchtoken" "monetate 156925593843210765", "ispersonalised" false }, "records" \[ { "name" "2026 spring/summer tees collection", "id" "313", "description" "curated collection of t shirts for spring/summer 2026" "searchclicktoken" "monetate nlisc2lje2njixe3dumynze3mjexoycd" }, { "name" "2025 fall/winter crewnecks & sweaters collection", "id" "316", "description" "curated collection of crewneck sweatshirts, long sleeve t shirts, and sweaters for fall/winter 2025 " "searchclicktoken" "monetate nlisc254tg5t63t5g3dumynze3mjexoype" }, { "name" "2026 spring/summer button up shirts collection", "id" "319", "description" "curated collection of button up dress shirts for wearing with suits or more business casual looks" "searchclicktoken" "monetate thg65y34dee2njixeumynze3mjexoycf" }, { additional records } ] } ] } category page records and personalized category page queries be aware that a site search query request for category page records that you've uploaded to monetate in a content pages dataset ( monetate category is included in the typeofrecords array) is not the same as a personalized category page query request a personalized site search request for monetate category content page records is a query that you make when you want to return category pages in response to a customer's search term anywhere on your site a personalized category page request occurs after a customer arrives on a product category page this request type searches for products based on products' category path(s) see personalized category page queries docid\ ealnr9q8q p8iwq9raccx for more information and request examples returning multiple record types as previously noted, you can configure a personalized site search request to identify complete records for both product records and records for one or more content page types here's an example of such a request along with its response example site search query request for product and content page records { "searchtoken" "monetate 180295149605129138", "recordqueries" \[ { "id" "productsearch", "typeofrequest" "search", "settings" { "typeofsearch" "wildcard and", "query" { "term" "battery lawn mowers" }, "limit" 5, "typeofrecords" \[ "monetate product" ], "fields" \[ "id", "name", "price", "typeofrecord" ] } }, { "id" "contentsearchcms", "typeofrequest" "search", "settings" { "typeofsearch" "wildcard and", "query" { "term" "battery lawn mowers" }, "limit" 3, "typeofrecords" \[ "monetate cms" ], "fields" \[ "id", "name", "description", "typeofrecord" ] } }, { "id" "contentsearchvideo", "typeofrequest" "search", "settings" { "typeofsearch" "wildcard and", "query" { "term" "battery lawn mowers" }, "limit" 3, "typeofrecords" \[ " video" ], "fields" \[ "id", "name", "description", "typeofrecord" ] } } ] } response { "queryresults" \[ { "id" "productsearch", "meta" { "qtime" 6, "noofresults" 5, "totalresultsfound" 57, "typeofsearch" "wildcard and", "offset" 0, "debugginginformation" {}, "notificationcode" 1, "searchedterm" "battery lawn mowers", "searchtoken" "monetate 180295149605129138", "ispersonalised" false }, "records" \[ { "id" "pl40vlm21d", "name" "powerlawn 40v 21 inch battery powered self propelled lawn mower", "price" "499 99" "typeofrecord" "monetate product", "searchclicktoken" "monetate z6hny8plq2eckqr3ualigan7uwp1s" }, { "id" "rg56vlm20d", "name" "rolling green 56v 18 inch cordless electric self propelled lawn mower", "price" "399 99" "typeofrecord" "monetate product", "searchclicktoken" "monetate c3jsy7pbq9vekdt7uzlacim4nbr0d" }, { "id" "pl40vlm20d", "name" "powerlawn 40v 20 inch battery powered self propelled lawn mower", "price" "449 99" "typeofrecord" "monetate product", "searchclicktoken" "monetate r7ftu1sxd6calky0icpqaon5mve8s" }, { additional records } ], }, { "id" "contentsearchcms", "meta" { "qtime" 6, "noofresults" 3, "totalresultsfound" 18, "typeofsearch" "wildcard and", "offset" 0, "debugginginformation" {}, "notificationcode" 1, "searchedterm" "battery lawn mowers", "searchtoken" "monetate 180295149605129138", "ispersonalised" false }, "records" \[ { "id" "2026 bplm bg", "name" "2026 battery powered lawn mower buyer's guide", "description" "overview of key mowing features, explanation of terms related to battery power and mower performance, and a review of improvements and innovations available in battery powered push lawn mowers for model year 2026" "typeofrecord" "monetate cms", "searchclicktoken" "monetate d4gfu3bmk6zeokw2ntxpleh8rcs1b" }, { "id" "ht swampgas4battery", "name" "power up your lawn care how to smartly swap gas powered mowers, trimmers, and more to battery power", "description" "guidance for selecting battery powered lawn mowers, string trimmers, edgers, and other lawn care equipment, with a comparison of run time, repair costs, lifespans of battery powered tools and gas powered tools" "typeofrecord" "monetate cms", "searchclicktoken" "monetate gax8cme5qldw3lnorb4j2ow4qmtv1" }, { "id" "101 lm", "name" "lawn mowers 101", "description" "introduction to the types of lawn mowers available for sale, covering manual reel mowers, gas powered mowers and mulchers, battery powered mowers, riding lawn mowers, and lawn tractors explanation of various design features such as side catchers, rear catchers, mulching attachments, horsepower, brushless engines, and more " "typeofrecord" "monetate cms", "searchclicktoken" "monetate r7ftu1sxd6calky0icpqaon5mve8s" }, { "id" "contentsearchvideo", "meta" { "qtime" 6, "noofresults" 3, "totalresultsfound" 9, "typeofsearch" "wildcard and", "offset" 0, "debugginginformation" {}, "notificationcode" 1, "searchedterm" "battery lawn mowers", "searchtoken" "monetate 180295149605129138", "ispersonalised" false }, "records" \[ { "id" "lct 2026 bplm t10", "name" "tested 2026's top battery powered lawn mowers", "description" "the lawn care team tests the top 10 battery powered push lawn mowers on a variety of grasses and turfs in a variety of environments to find out which models from the best selling brands—including powerlawn, rolling green, jandi, and more—are worth the investment" "typeofrecord" " video", "searchclicktoken" "monetate 6nphoc1t3l8d4hwxelg2z5m7hk0tl" }, { "id" "lct motors", "name" "brush up on brushless and brushed battery powered lawn equipment", "description" "the lawn care team demonstrates the differences between brushless and brushed motors used in battery powered lawn mowers, string trimmers, and other lawn care tools" "typeofrecord" " video", "searchclicktoken" "monetate 8wtlkdyjaq7zu9deumgqfueyyq4uz" }, { "id" "lct bplm options", "name" "mow power choosing the right battery powered lawn mower for your yard", "description" "the lawn care team breaks down how to determine the deck width, battery amp hours, battery voltage, and other options available for battery powered lawn mowers can best meet your lawn care needs" "typeofrecord" " video", "searchclicktoken" "monetate j8m3geinp2vc0bj7upzkuuw2b7b2t" } ] } ] } monetate recommends passing only one record type value in each typeofrecords occurence in a request as shown in the example instead of combining all the record type values into one typeofrecords array if you pass multiple record type values in a single typeofrecords occurence, then personalized search returns all the results records without any defined order, which can make it harder for you to format