Category-based Widget API

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

Endpoints

Production: https://pathways.dxpapi.com/api/v2/widgets/category/{widget_id}
Staging: https://pathways-staging.dxpapi.com/api/v2/widgets/category/{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 in 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 identifierDescription
"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":"category",
   "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": "category",
      "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.

Language
Click Try It! to start a request and see the response here!