Walkthrough — Build a content search results page
Scenario: Esteban wants recipes
Esteban's mother gave him a paellera, which is a carbon steel pan designed to cook a paella. He's looking for Spanish recipes and cooking advice at example.com site, which is a popular site for household goods and advice. He plans to invite his mother to dinner and impress her by serving her a traditional Valencian paella.
example.com has 19 items that fit Esteban's search criteria, including paella recipes, articles about traditional cooking methods, and recommendations for ingredients and equipment.
Esteban enters cooking valencian paella in the search field, which triggers a content search with his keywords forming the fundamental part of the request. Because this is a content search, the call requires the data_type parameter set to content. Calls that don't set data_type at all return products because product is the default data_type setting.
Here's the request:
GET http://core.dxpapi.com/api/v1/core/? account_id=<Bloomreach Provided Account ID> &domain_key=example_com &request_id=1597706996836 &url=http://www.example.com/index.html?q=cooking%20valencian%20paella &data_type=content &request_type=search &search_type=keyword &q=cooking valencian paella &fl=title,author &fq=content_type:"recipe" OR "advice" &rows=10 &start=0
Walk through the request
Now let's walk through this request and see what the call is doing.
Lines 1 - 5
The call says who's sending it, how to identify it, and where it started
It's sending a query to the endpoint:
The first parameters in the example.com establish which Bloomreach customer is making the call. The account ID is the Bloomreach provided unique identifier for your account, and the domain key is example_com. Notice that account_id doesn't have a leading ampersand:
The request ID sets a unique identifier for this specific request:
And the URL indicates the absolute URL where Esteban started the request:
What kind of data is the call searching?
The data type directs the call to search non-product content:
If you have experience using earlier versions of Commerce Search and Categories, then the data_type parameter might be new to you. Its default value is product, so you don't need to include it in your product search calls. You only need it for content searches. All content searches require the data_type parameter value to be content.
Lines 7 - 8
What type of call is it?
The next parameters establish that the type of the request is a search, and the type of search is a keyword. It's a keyword search because Esteban entered his query, cooking valencian paella, in a search field on the example.com site. He might decide to do a category search later by clicking through categories like rice and chicken rather than typing keywords.
What are the search terms?
Now the call sends the fundamental part about Esteban's query: the keywords that he typed in the search field. His keywords are cooking valencian paella, so the call specifies cooking valencian paella for the q parameter value.
What information does the call retrieve?
The fl parameter is populated with several values that provide the essential information about each content item that Esteban needs when he determines which items he wants to look at more closely. This particular call includes the title and author.
What type of content is the call looking for?
Esteban is looking for recipes and advice in his quest to cook the perfect Valencian paella. He focuses his search results by selecting two types of content: recipe and advice. The query sends these selections as a filter on the type facet:
Filtering search results You can learn more about filters and the fq parameter in Filtering search results.
Lines 12 - 13
How many content items are on a page?
The call stipulates a maximum of 10 content items per page of results, starting with the first item. Each item is a row, and that first items is row zero, not one. Therefore, the value of start is also 0. Subsequent pages update the start value to show the next set of items.
The start parameter identifies the first items, and the rows parameter specifies the maximum number of products to display in a page of search results.
>Can you explain that more?
Remember that example.com has 19 items that fit Esteban's criteria. If he decides to see the remaining nine items, then the call updates the start value to 10. The updated start value isn't 11 because the first start value is 0. It's okay that the value of rows remains 10 even though there are 19 items total, of which nine are relegated to the second page of results. The rows parameter value is simply the maximum the number of items on a page, not the specific number.
After finding the information he needs about paellas, Esteban starts a new search for advice about wine. That search produces 46 products. When he looks at the fifth page of those results, the start parameter value changes to 40. Because the maximum number of products per page remains 10, the value of rows remains the same.
Disclaimer for items marked "In pilot phase"
Please note that this product or feature is in pre-release “pilot phase” and is made available to select participants from time to time for the purpose of providing feedback on the quality and usability of the “pilot phase” product or feature (the “Pilot Products”). Pilot Products are still undergoing final testing and evaluation and ARE PROVIDED ON AN “AS IS” AND “AS AVAILABLE” BASIS WITHOUT ANY WARRANTIES, WHETHER EXPRESS OR IMPLIED, AS TO THE QUALITY, SUITABILITY, USABILITY MERCHANTABILITY, NON-INFRINGEMENT, ACCURACY, COMPLETENESS, PERFORMANCE AND FITNESS FOR A PARTICULAR PURPOSE OF THE PRODUCT OR FEATURE AND WILL NOT BE LIABLE FOR ANY LOSS, WHETHER SUCH LOSS IS DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL, SUFFERED BY ANY PARTY AS A RESULT OF THEIR USE OF THE PRODUCT OR FEATURE. Bloomreach is not obligated to offer any maintenance, technical or other support on the Pilot Products, continue to offer any Pilot Products, or announce or make available a commercial version of the Pilot Products to anyone in the future. Should a commercial version be made available, it may have features or functionality that are different from those found in the Pilot Products.
Should you encounter any bugs, glitches, lack of functionality or other problems with respect to the Pilot Products, please let us know immediately so we can rectify these accordingly. Your help in this regard is greatly appreciated.