Walkthrough — Build a Product Search Results Page - Bloomreach Experience - Open Source CMS

Walkthrough — Build a Product Search Results Page

Scenario

Lucia is a customer who is looking for a dress to wear to a particular event. Here are the characteristics of the perfect dress for her:

Colors

Fabrics

Sizes

Designers

Styles

Budget

Event formality

Red

Purple

Fuchsia

Silk

Cotton

8 – 10

Pinup

Flutter

Rockabilly

Tea length

$100 – $200

Cocktail

Example.com is a retail site that sells a wide variety of products, including dresses that Lucia might like.

Jake is a web developer, specializing in the website's digital merchandising efforts for its apparel categories.

Let's start very simple
For this walkthrough, we look at the simplest API call that can return valid results. After we walk through the simplest call, we pull items from the scenario to add complexity to the call. We also run what-if scenarios that deviate from the original so that we can see what happens.

The Request

Lucia enters dresses in the search field, which triggers a product search with her keyword forming the fundamental part of the request.

Here's the request:

Request: keyword search for dresses

GET http://core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach Provided Account ID>
&auth_key=jazzhands
&domain_key=example_com
&request_id=8438674500839
&_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55
&ref_url=http://www.example.com/home
&url=http://www.example.com/index.html?q=dresses
&request_type=search
&search_type=keyword
&q=dresses
&fl=pid,title,brand,price,sale_price,thumb_image,url,description
&rows=10
&start=0

You can run this call against sample data.

Walk through the request

Now let's walk through this request and see what the call is doing. In particular, we examine the parameters and values that Jake uses to form the request for Lucia's search.

Line 1

Where does the call go?

Jake starts the API request by sending Lucia's search query to the endpoint. This endpoint is your endpoint, too.

1

GET http://core.dxpapi.com/api/v1/core/?

Lines 2 - 4

How do you identify your call?

These first parameters identify example as a Bloomreach customer sending an API request.

Account ID

Bloomreach assigns you a numerical account ID, which is part of the information package you receive during your integration kickoff meeting.

2

account_id=<Bloomreach Provided Account ID>

No leading ampersand for account_id
The account_id parameter doesn't have a leading ampersand. This rule applies only to account_id.

All other parameters in your API calls require a leading ampersand. http://core.dxpapi.com/api/v1/core/?account_id=value&auth_key=value&_br_uid_2=value&domain_key=value ...

Authorization key

For this walkthrough, Jake is using an obviously fake authorization key. As with any other password, don't share your auth_key parameter value even if you're only demonstrating how to form an API request.

3

&auth_key=jazzhands

Leave auth_key parameter values empty for client-side calls

We don't discuss client-side calls in this walkthrough. However, if you do use client-side calls for some of your Bloomreach requests, then do not enter an auth_key value in those client-side calls. Pass the auth_key parameter with an empty value in client-side calls.

The auth_key value is a private authorization key. If you include your valid auth_key value in client-side calls, then you inadvertently expose that private information to everybody.

Your Bloomreach representative provides you with your authorization key during your integration kickoff meeting. Expect a value that looks something like this: 3c641ak5b543cb3a642da . If you don't have an authorization key, then contact your Bloomreach representative right away.

Best practice: avoid empty auth_key values in server-side calls
Bloomreach doesn't strictly enforce auth_key values. You can technically send an API request with an empty auth_key. As a best practice, we recommend that you always include your Bloomreach-provided auth_key value with all of your server-side calls.

Domain key

Your Bloomreach representative provides this key during your integration kickoff meeting. If you don't have an authorization key, then contact your Bloomreach representative right away.

4

&domain_key=example_com

Lines 5 - 8

How do you track the call and related clicks?

These parameters uniquely identify the call and track your visitors' interactions on your site.

Request ID

Jake assigns the call a unique ID. He uses a random number generator to create unique 13-digit IDs for example's request_id values. The request ID sets a unique, 13-digit identifier for each specific request, enabling click-tracking.

5

&request_id=8438674518839

Best practice: always include a unique request_id value
Click-tracking requires 13-digit, unique numerical values for request_id parameters.

Bloomreach doesn't strictly enforce request_id value requirements. For example, you can enter  test  as your value for each instance of the request_id parameter without triggering an error message. However, entering an invalid or empty value disables click-tracking and many Bloomreach features. Your Bloomreach representative can offer only limited help if your API requests don't use valid, unique request_id values.

Tracking cookie

Jake assigns a cookie for his _br_uid_2 parameter value. This value is a first-party cookie created by the Bloomreach tracking pixel library (BrTrk). The cookie creates a unique, anonymous identifier for every browser or device.

6

&_br_uid_2=uid=7797686432023:v=11.5:ts=1428617911187:hc=55

Best practice: always include a unique _br_uid_2 value
Many Bloomreach features and services require the _br_uid_2 cookie to be passed with every API call.

Bloomreach doesn't strictly enforce _br_uid_2 value requirements. But without the cookie, you can't use features and services like personalization and A/B testing.

Referring page

Jake's ref_url parameter value is populated when the Bloomreach pixel fires as Lucia clicks a link. This value identifies which page was loaded in Lucia's browser when she clicked a link to move to the current page. Digital merchandisers and marketers at example use this information to track Lucia's activities on the site, and gain a better understanding of what she wants to see.

7

&ref_url=http://www.example.com/home

Do you want more information about referring pages and URLs?

Query page

Jake uses the url parameter to track where Lucia started her search query. The url parameter value is the absolute URL of Lucia's starting point for her dresses query.

8

&url=http://www.example.com/index.html?q=dresses

Tip
An absolute URL always includes the domain and the protocol. In the example for example, the domain is www.example.com , and the protocol for the page where Lucia started her request is http:// .

Don't use a relative domain for your url parameter values. We need your absolute URL so we can resolve any canonicalization issues. Further, some search bots can have trouble with relative URLs, which can then have a deleterious effect on your site's SEO value in major search engines.

Lines 9 - 10

What type of call is it?

Two parameters establish that the type of Jake's request is a search, and the type of this search is a keyword. Jake knows that Lucia's search is a keyword search because she entered a keyword in the Search box on example's site.

All keyword search API calls must be defined with these specific settings: search for request_type and keyword for search_type.

9

10

&request_type=search

&search_type=keyword

What if Lucia decides to do a different kind of search?
The value of the request_type and search_type parameters change, depending on the type of search Lucia chooses to do. For example, Lucia might decide to click through categories like apparel and dress rather than typing keywords. That kind of search is called a category search, which uses category as the search_type parameter instead of keyword.Take a look at the quick reference tables for other APIs to see how these parameters differ as the type of search or other query differs.

Line 11

What are the search terms?

Now Jake sends the fundamental part about Lucia's query: the keyword that she typed in the Search box. Her keyword is dresses, so Jake assigns dresses to the call's q parameter value.

11

&q=dresses

What if Lucia uses multiple words in her search query?
We secretly know that Lucia wants a rockabilly style dress. Instead of simply dresses, she might enter rockabilly dresses as her starting query. When that happens, Jake can either percent encode the space between Lucia's two terms, or he can simply pass the space in his q parameter value without any encoding. Either method is acceptable.

If you decide to percent encode spaces, then we recommend that you follow standard URL percent-encoding conventions. The standard for spaces is %20. For example:

&q=rockabilly%20dresses

Line 12

What product information does the call retrieve?

Jake populates the fl parameter with attributes that describe each product that he wants returned in the API response. Lucia can use this information when she determines which dresses she wants to look at more closely, and makes her subsequent purchasing decisions.

12

&fl=pid,title,brand,price,sale_price,thumb_image,url,description

Tips

● The pid attribute is the only required value for the fl parameter.
● Each attribute in the parameter value must be separated with a comma.
● Values for the fl parameter depend on example's product feed. If the product feed doesn't include a key-value pair for a particular field, then that field can't be an attribute in the flparameter value.

Jake is using a moderately detailed value for his fl parameter. He starts with the pid attribute because all fl parameter values must include pid. Conceivably, he can choose to pass only pidfor his fl parameter. The corresponding response for such a value contains only product IDs, which can be important for certain use cases, but doesn't generally yield exciting results. Jake's other attributes indicate that he wants the call to retrieve information like the name of the products and pricing information.

 The fl parameter specifies which product information you want the request to retrieve
Don't confuse the set of attributes in the fl parameter value with the product attributes that you want to display in a search results page. The fl parameter value specifies the information that you need in your search API response, not the appearance of the results page itself. For example, you need the pid attribute in your fl parameter value because pid is the product ID. If you don't include pid, then the response can't include products. But that doesn't mean you have to show pid values in search results pages.

For example, Jake might decide to use the pid, title and thumb_image attributes for his fl parameter value:
&fl=pid,title,thumb_image

The response includes a product ID, product name, and a thumb image for every product returned. But when he extracts information from the response to build Lucia's search results page, he might choose to include only the name and thumb image for returned products.

Lines 13 - 14

How many products are on a page?

The call stipulates a maximum of 10 products per page of results, starting with the first product. Each product is a row, and that first product 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 products. The maximum values are 200 for the rows parameter and 10000 for the start parameter.

The start parameter identifies the first product, and the rows parameter specifies the maximum number of products to display in a page of search results.

13

14

&rows=10

&start=0

Can you explain that more?
example has 122 dresses that fit Lucia's criteria. If she decides to see the second page of her search results, then Jake updates the call's start value to 10. The updated start value isn't 11 because the first start value is always 0.
&rows=10
&start=10
After finding her dress, let's say that Lucia starts a new search for complementary earrings. That search produces 46 products. When she 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. It's okay that the value of rows remains 10 even though there are 46 products total. The rows parameter value is simply the maximum number of products on a page, not the specific number of products on the page. The last 6 of the 46 matching products are relegated to the last page of results.

&rows=10

&start=40

Quick reference: request parameters

All the parameters that we use in this walkthrough's API request are in this quick reference. This quick reference provides only basic descriptions, expected value types, and examples taken directly from the walkthrough's request. Keep in mind that your own values differ according to your own use cases.

_br_uid_2

A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). This cookie creates a unique, anonymous identifier for every browser or device.

The _br_uid_2 cookie is already encoded
Don't encode the cookie parameter value: _br_uid_2. Use this value exactly as it comes. It's already encoded.

 ✅ &_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55

Value type

string

Example value

&_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55

account_id

Your site's numerical Bloomreach account ID. Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting.

Notify your Bloomreach Representative
If you don't have a Bloomreach account ID, then let your Bloomreach representative know immediately. You can't send any API calls without your account ID.

Value type

integer

Example value

&account_id=<Bloomreach Provided Account ID>

auth_key

The Bloomreach-provided authentication key for the Bloomreach account that's sending the request.

Leave auth_key parameter values empty for client-side calls

If you use client-side calls for any of your Bloomreach requests, then do not enter an auth_key value in those client-side calls. Pass the auth_key with an empty value in client-side calls.

The auth_key value is a private authorization key. If you include your valid auth_key value in client-side calls, then you inadvertently expose that private information to everybody.

Value type

string

Example value

&auth_key=jazzhands

Your own auth_key value looks very different from this example. We're using an odd example value to reinforce the importance of treating this key like you treat other keys like your email login credentials: don't share it.

domain_key

Your site domain's ID, which is provided by Bloomreach. This ID is for the domain that you want to receive your Bloomreach API requests.

This parameter identifies the specific site version when the one account ID hosts multiple site versions with unique characteristics, such as language versions. Bloomreach uses your domain_key parameter value to ensure that only the data that pertains to that site version is used for query and analytics features, such as autosuggestions.

Value type

string

Example value

&domain_key=example_com

fl

The attributes that you want returned in your API response, such as product IDs and prices. All fl parameters must include pid as one of their values. You can include other attributes from your product feed.

Tip
Include all the attributes from your product feed that you want to include in search results, not just the attributes that you want to be returned as objects in your API response. Your search results pages are built from your API responses. Therefore, search results pages can only include attributes that are returned in API responses.

Value type

string

Example value

&fl=pid,title,brand,price,sale_price,thumb_image,url,description

Example value for Content

&fl=cid,title,thumb_image,url,description

Comma-separated values
Separate multiple attributes with a comma: &fl=pid,title,thumb_image,price

q

Your site visitor's search query. Search queries are composed of one or more terms.

Tip
You can percent encode spaces between terms, or you can leave the spaces the way they are. The correct code is %20 if you choose to percent encode spaces in multi-term search queries.

Value type

string

Example value

&q=dresses

ref_url

The URL of the page or HTTP referrer where the request is started.

Value type

string

Example value

&ref_url=http://www.example.com/home

request_id

An ID to track site visitor clicks. We recommend that you generate unique, random values of 13 digits to enable click-tracking.

Bloomreach doesn't automatically enforce the requirements for this parameter. For example, you can enter test as your value for each instance of the request_id parameter without triggering an error message. However, using a unique value allows us to help you if you encounter a problem.

Value type

string

Example value

&request_id=1597706996836

request_type

The type of API request. Choose the value that fits your use case:

  • search
  • suggest
  • jfy
  • mlt
  • thematic

Value type

string (enum)

Use search for search API calls
The only correct &request_type value for a category search API call is search.

rows

The number of matching items to return per results page in the API response. The maximum value is 200.

Tip
To enhance performance, limit this value to the number of items that you think is reasonable for a single page of search results.

Value type

integer

Example value

&rows=10

search_type

The type of search. Choose the value that fits your use case:

  • keyword
  • category

Value type

string (enum)

Use keyword for this tutorial's use case

This tutorial walks through a filtered keyword search use case. The only correct &search_type value for this tutorial's use case is keyword.

start

The number of the first item on a page of results. For example, the first item on the first page is 0, making the start value also 0. The maximum value is 10000.

Value type

integer

Example value

&start=0

url

The absolute URL of the page where the request is initiated.

Use the absolute URL
Don't use a relative URL for your url parameter value.

Value type

string

Example value

&url=http://www.example.com/index.html?q=dresses

The Response

Lucia's keyword search for dresses initiates an API request, which sends a JSON response with her search results. Jake uses this API response to build the search results page for Lucia.

Here's the response, which is truncated so we can focus on just the search results themselves for now:

Response: keyword search for dresses
  "response": {
    "numFound": 5248,
    "start": 0,
    "docs": [
      {
        "sale_price": 139.99,
        "price": 201.99,
        "description": "This flowery dress breathes paradise into your summer wardrobe.
           It's lovely with tan sandals and a stroll along the boardwalk.
           80% cotton, 20% linen. Machine wash cold, line dry.",
        "title": "Tropical Blossoms",
        "url": "http://www.example.com/Product/Product.aspx?br=BLMQ&category=dress&productid=89549840841",
        "brand": "Flutter",
        "pid": "89549840841",
        "thumb_image": "http://www.example.com/images/sm/tropical-blossoms-flutter.jpg",
        "variants": [
        ]
      },
...
    ]
  },
}

The actual response has more objects in the docs array, and some of the objects after docs are collapsed.

New to JSON?

Here are some tips about JSON formatting to help you understand the response:

  • Data is represented by key:value pairs. We often refer to keys in JSON responses as product attributes because we want to reinforce the idea that these key:value pairs are describing attributes of products, which we find in your product catalog.

  • Curly braces contain objects.

  • Square brackets contain arrays.
  • Colons separate keys (attributes) and values.
  • Commas separate key:value pairs.
  • Strings are surrounded by double quotes: "example_string"

  • Numbers don't use strings: "price": 201.99

If you need to understand JSON in more depth, then a good place to start is W3Schools.

Walk through the Response

Now let's walk through this response and see how it's formed by the request.

Lines 1 - 3

The response summarizes the results

It's identifying itself as a response array, and opening its contents with the starting curly bracket:

1

"response": {

The first field in the example counts the number of products that fit Lucia's search criteria. Generically, the value for the numFound field is the number of records that the API request found that match the request's query. Our example API request found 5,248 products that match &q=dresses.

 "Product" is a convenient term
Because we're walking through a product search, we're referring to these records as products. For a non-product content search, you might see a term like article to describe reviews, advice, and other non-product information.

2

"numFound": 5248,

The start field refers to the first product to appear in the first page of results. This field value comes directly from the request's start parameter value.

3

"start": 0,

What happens when Lucia opens the next page of results?
example has more products matching Lucia's very simple search query than the request's rows parameter can accommodate on one page. To see the next page of matching products, Lucia clicks the Next button on her search results page. Her action sends an updated search request that sets a new start parameter value:
&start=10
The corresponding search response also updates the start field value to 10:
"start": 10,
Each time Lucia loads the next page of search results, she updates the start parameter in the request and the start field in the response. Because 5,248 products is an unreasonable number of undifferentiated items for her view, she's likely to apply filters to her search. But theoretically, she can continue to click the Next button hundreds of times to view all the matching products to a maximum of 10000.

Lines 4 - 5

Which products are in the response?

The docs array contains objects representing the products that the request found. Jake uses these objects to populate the search results page. This array introduces its collection with an opening square bracket. Curly brackets delineate each product's set of attributes within the docs array.

4

5

"docs": [

  {

Lines 6 - 22


What are the contents of the docs array?

 Only one product in the example response
Our example truncates the contents of the docs array, showing only one object. Because example has more than the single product in this truncated response, the full response continues with the next product at Line 19, continuing until all 5,248 matching products are accounted for. A closing square bracket indicates the end of the doc array's contents.

The example product in our truncated response is a dress called Tropical Blossoms. The docs array contains many of the dress' attributes requested in Jake's &fl parameter.

 Your product feed must be current and complete
The contents of each object depend on the interaction between the API request and the product feed. Only fields that are in the product feed can be represented in the response. For example, Jake didn't include the keywords field in example's product feed. Therefore, the API response can't include a keyword like prom or beach in the search results. Jake made the decision to exclude keywords from the product feed because example made a business decision to use different methods to describe its products.
What happens if I send only pid for my &fl parameter value?
The product ID in our example response is "pid": "89549840841". If Jake decides to send a request that stipulates only pid for his &fl parameter value, then the corresponding response can only include pid values in the docs array. While pid is the only required value for the &fl parameter in API requests, including only the pid attribute retrieves responses of limited value for building a search results page with rich, valuable content. However, if your use case requires only a report of all product IDs, then sending a request with simply &fl=pidis fine.
Your product feed populates the values of product attributes
The values of each product attribute are determined by the contents of your product feed. If you want to change these values in your API responses, then you need to change the values in your product feed.

Let's walk through what you're seeing in the docs array in Jake's response.

Your product feed populates the values of product attributes
The values of each product attribute are determined by the contents of your product feed. If you want to change these values in your API responses, then you need to change the values in your product feed.

>sale_price and price attributes

6

7

"sale_price": 139.99,

"price": 201.99

The sale_price attribute is the sale price of the product, and the price attribute is the product's regular price.

Some Bloomreach customers prefer to use only the sale_price attribute in their &fl parameter values rather than both sale_price and price, These customers simply update sale_price in their product feed to reflect the current price of the product. example's best practices require that Jake use both values in his API requests.

The Tropical Blossoms dress is currently on sale for $139.99. When Tropical Blossoms is no longer on sale tomorrow, Jake's updated product feed won't have a value for sale_price, and sale_price won't appear in his API responses.

>description attribute

8

9

10

"description": "This flowery dress breathes paradise into your summer wardrobe.

           It's lovely with tan sandals and a stroll along the boardwalk.

           80% cotton, 20% linen. Machine wash cold, line dry.",

The description attribute is a text field for describing the product. You can include any text that you like in your product feed's description field, which in turn populates the product's description attribute in your API responses.

Per example's best practices, Jake's product feed uses the manufacturer's own text to describe the product. Jake relies on his product feed's description field to include that description for all products returned in his API response.

>title attribute

11

"title": "Tropical Blossoms",

The title attribute is usually the name of the product. Per example's best practices, Jake uses the manufacturer's own product name for his product titles.

>url attribute

12

"url": "http://www.example.com/Product/Product.aspx?br=BLMQ&category=dress&productid=89549840841",

The url attribute is the canonical or absolute URL of the product page.

>brand attribute

13

"brand": "Flutter",

The brand attribute is the designer, manufacturer, brand, or similar descriptor of the creator of the product. Lucia thinks of the brands she sees on example's site as designers. That's because Homea refers to the brands of its apparel and accessories as designers. For example, Lucia can do a category search by clicking the Featured Designers button on the example home page.

>pid attribute

14

"pid": "89549840841",

The pid attribute is the product ID. Every product in example's product feed must have a unique product ID. Jake's fl parameter values always include pid so that the API request can find matching products and put them in the response.
You must include pid in your product feed and in the fl parameter values of your search API requests.

 Are you new to JSON?
Numbers don't use double quotes in JSON, but Jake's pid value does use them because it only looks like a number; it's really a string. Many Bloomreach customers have alphanumeric product IDs in their product catalogs.

>thumb_image attribute

15

"thumb_image": "http://www.example.com/images/sm/tropical-blossoms-flutter.jpg",

The thumb_image attribute is a thumbnail image of the product. When Lucia looks at her search results, she sees a thumbnail image for the products that match her search query. When she clicks the Tropical Blossoms dress, she opens its product page and sees additional images. These images are generally larger than thumbnail images, though they don't technically have to be larger. Jake's product feed stores these additional images in the large_image field. We don't see large_image in this response because Jake didn't include the large_image attribute in the &fl parameter of his request. He uses the large_image attribute for product pages, not for search results.

You can learn more about thumb_image and large_image in Add images to your product feed.

variants array

Jakes's response includes an empty variants array nested inside docs. His call specified only product-level data, not SKU data. However, if he includes SKU attributes like sku_size and skuid in his request's fl parameter, then his variants array includes SKU data.

example's product feed includes information about each product SKU, which is a specific variation of a product like a size and color. Each docs array includes a nested variants array, which describes variant product attributes, especially for different SKUs. Some Bloomreach customers assign a different pid value for every product in their feed rather than use SKU data to differentiate variations of products. For example, the Rockabilly Rose site has a dress called Flip Flap, Size 8, Yellow with the product ID, DR34289. Another dress is called Flip Flap, Size 10, Yellow with the product ID, DR20944. Rockabilly Rose doesn't use SKUs to indicate that these products are related. example does.

If your product feed doesn't have product SKU variations, then your variants arrays are empty. Jake's variants array is empty because the fl parameter in his call didn't include any SKU attributes.

 

Response elements and the fl parameter

This table shows you specific elements in the response and how they correspond to values in the fl parameter of Jake's request.

Response element

Request &fl value

Type

Additional information

"sale_price": 139.99,
"price":201.99,
 &fl=price,sale_price
Integer The sale_price attribute is the price of the product when it's on sale. Some Bloomreach customers prefer to use only the sale_priceattribute in their &fl parameter values rather than both sale_price and price, but example's best practices require that Jake use both values in his API requests.
"description": "This flowery dress 
breathes paradise 
into your wardrobe. 
80% cotton, 20% linen. 
Machine wash cold, line dry.",
 &fl=description

String

Per example's best practices, Jake's product feed uses the manufacturer's own text describing the product. Jake uses the description attribute to include that description for all products returned in his API response.

"title": "Tropical Blossoms,
&fl=title
String The title attribute is usually the name of the product. Per example's best practices, Jake uses the manufacturer's own product name for his product titles.

 

What's next?

The request and response we just walked through are probably too simple to adequately cover your needs. These are meant to get you started. Now that you know how to retrieve search results, you might like to filter and sort those results.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?