Keyword-based Widget API

get https://pathways.dxpapi.com/api/v2/widgets/keyword/{widget_id}

time	status	user agent
Retrieving recent requests…

Loading…

This API allows you to fetch a keyword-based widget response.

Endpoints

Production: https://pathways.dxpapi.com/api/v2/widgets/keyword/{widget_id}
Staging: https://pathways-staging.dxpapi.com/api/v2/widgets/keyword/{widget_id}

The widget_id can be found in the Widget Configurator in the Dashboard.

How do facets appear in the Pathways API response?

Facets can be returned in the Pathways API response by setting the parameter facet=true. Note that the facets in the Pathways API response are structured differently compared to the Search API response in order to not depend on Javascript implementations.

V3 Facet Response: The V3 facet response format merges all facets together, irrespective of whether it is a numeric or a text facet. All the facets are now unified in the "fields" object.

The Legacy API response returned text and range facets separately in fields and ranges objects, respectively. You can find descriptions of facet type identifiers below:

Facet type identifier	Description
"type":"text",	This displays the count of individual text facet values.
"type":"number",	This displays the count of individual numeric facet values.
"type":"number-range",	This can be used to identify ranged facets. It displays the facet values as predefined range buckets and specifies the count for each bucket.
"type":"number_stats",	This can be used to identify the numeric facets that display a slider widget. The slider has a maximum and minimum value. Sliders allow shoppers to adjust the filter range.

"metadata":{
   "widget":{
      
   },
   "id":"nj37wglr",
   "name":"Search Pathway",
   "description":"",
   "type":"search",
   "rid":"f259084f-e878-4d5f-a7d5-2ea350f971c1""response":{
      "personalized_results":false,
      "fallback":" ",
      "recall":"pure"
   },
   "query":{
      
   }
},
"facet":{
   "category":[
      
   ],
   "fields":[
      {
         "key":"Size",
         "type":"text",
         "value":[
            
         ]
      ]
   },
   {
      "key":"Color",
      "type":"number",
      "value":[
         
      ]
   },
   {
      "key":"sale_price_test",
      "type":"number_range",
      "value":[
         
      ]
   }
],

{
  "response": {
    "numFound": 256,
    "start": 0,
    "docs": []
  },
  "metadata": {
    "widget": {
      "id": "abcdef",
      "name": "Homeoasis Brand Highlight",
      "description": "Highlights Homeoasis products",
      "type": "search",
      "rid": "aaaabbbbccccddddeeeeffff11112222"
    },
    "query": {},
    "response": {
      "personalized_results": false,
      "fallback": "",
      "recall": "pure"
    }
  },
  "facet": {
    "category": [
      {
        "cat_id": "cat12345678",
        "cat_name": "Bedsheets",
        "count": 30,
        "children": []
      },
      ...
    ],
    "fields": [
      {
        "key": "Color",
        "value": [
          {
            "count": 10,
            "name": "Blue"
          },
          {
            "count": 10,
            "name": "Black"
          },
          {
            "count": 10,
            "name": "White"
          }
        ]
      },
      {  
        "key": "Price",
        "value": [
          {
            "count": 10,
            "name": "19.99"
          },
          {
            "count": 10,
            "name": "29.99"
          },
          {
            "count": 10,
            "name": "39.99"
          }
        ]
      }
    ],
    "ranges": [
      {
        "key": "Price",
        "value": [
          {
            "count": 10,
            "start": "*",
            "end": 20
          },
          {
            "count": 20,
            "start": 20.01,
            "end": 40
          }
        ]
      }
    ],
    "query": {}
  }
}

📘
Customers whose go-live date is after September 7, 2023 will be on V3 Facet response format by default. If you’re on the legacy format and would like to implement the new Facet response format, kindly contact your Bloomreach Services representative.

👍
For more detailed information of any of the following API parameters, refer to the Recommendations and Pathways parameters reference.

Path Params

widget_id

string

required

Defaults to 1jwq4qjz

The ID of the widget, which can be found in the Widget Configurator in the Dashboard.

The example value shown here, 1jwq4qjz, is included for your convenience to send a request with Try It.

Query Params

account_id

int32

required

Defaults to 6702

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.

The example value shown here, 6702, is included for your convenience to send a request with Try It.

_br_uid_2

string

required

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

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

Use the default value provided, which is already encoded.

domain_key

string

required

Defaults to documentation_site

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.

The example value shown here, documentation_site, is included for your convenience to send a request with Try It.

query

string

required

Defaults to cable

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

You can percent encode spaces between terms as %20, or you can leave the spaces unencoded.

The example value shown here, cable, is included for your convenience to send a request with Try It.

request_id

string

required

An ID to track site visitor clicks. We recommend that you generate unique, random values of 13 digits to enable click-tracking. The request_id is also important for debugging.

url

string

required

Defaults to https://www.documentation-site.com

The absolute URL of the page where the request is initiated. Do not use a relative URL.

The example value shown here, https://www.documentation-site.com, is included for your convenience to send a request with Try It.

fields

string

A comma-separated list of fields to be sent in the request.

Alternatively, you may configure the fields in the Widget Configurator in the Dashboard instead. This parameter is required if not sent via the Dashboard.

facet

boolean

Defaults to false

Facets are disabled by default. To enable facets, set facet=true.

filter

string

The filter parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. Any facet that you want to filter must be in your feed.

Attributes must be enabled and mapped by Bloomreach. Let your Bloomreach representative know which attributes in your content feed you want to apply as filters to search results.

You can filter results based on numeric ranges. For example, &filter=(price:["100" TO "*"]). Please note that a negative filter on ranges is not supported.

To provide multiple filters, send multiple filter parameters. For example, &filter=(price:["*" TO "100"])&filter=(color_groups: ("blue"))

filter_facet

string

With the filter parameter, after a user selects a facet value for filtering, the other facet values in that field are not returned by the API and are no longer visible. The filter_facet parameter allows other facet values to be returned after a facet value has been selected.

filter_facet does not support complex boolean operations, but they can be supported by including both filter and filter_facet.

Note that the attributes used in filter will not return all values after the user selects a facet value in that field. Example values:

Single filter with multiple values
&filter_facet=color:"red" OR "purple"

Multiple filters on different attributes
&filter_facet=color:"red"&filter_facet=brand:"Bloomreach"

ref_url

string

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

rows

int32

The number of matching items to return per results page in the API response. The maximum value is 200. The result size is used from the Dashboard if it is not sent in the API.

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

start

int32

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.

user_id

string

The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. The parameter captures user IDs from the customer side and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system.

Use an anonymous string. Don't use email or other personally identifiable information.

view_id

string

A unique identifier for a specific view of your product catalog. If you have multiple versions of your site, each with their own product catalog characteristics like product titles and prices, then add view_id to your call. Bloomreach uses your view_id parameter value to display the right product information for your customers based on their individual site views.

You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and product catalog.