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 personalized site search queries /#category page records and personalized category page queries , or a personalized site search queries /#returning content page records if you've implemented the monetate javascript 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 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 using the fields array by default, records returned in the response include values for all attributes in the mapped product catalog, including custom attributes 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 true false 130false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type 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 personalized site search queries 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 true false 161false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type 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 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 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 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 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