How to use the JSON widget API - Bloomreach Experience - Open Source CMS

How to use the JSON widget API

Getting JSON organic widget responses

This page shows you an example request and response that can help you form your own widget JSON API calls for your site. If you need more information about parameters, then take a look at the quick reference table, which describes the parameters and provides example values.

The display requirements are still the same as Bloomreach served HTML responses as highlighted here in Related categories, related items and related products widgets and have to be adhered for product efficacy. 

Request

During integration kickoff, Bloomreach gives you an example API request that's customized with your account information. You can use that example request by adding your own values to the remaining parameters.

Here's an example JSON widget API call:

Example JSON widget API request

GET http://example.brsrvr.com/v3/fetch_widget
?url=http%3A//www.example.com/product%3Fid%3D999
&acct_id=<Bloomreach Provided Account ID>
&acct_auth=jazzhands
&ptype=product
&user_agent=Mozilla%2F5.0+%28compatible%3B+Googlebot%29
&ref=http%3A//www.example.com/search%3Fq%3Fdresses
&pstatus=ok
&output_format=br_json
  • output_format must be set to  br_json. This parameter defaults to html which is used in HTML widget integrations.

Example truncated response

Here's a truncated example response. 

{ 
   "related-category":[ 
      { 
         "anchor":"Pain Relief",
         "url":"/health/medicine-cabinet/pain-relief.html"
      }
   ],
   "br_iuid":"ZXhhbXBsZS5jb20vZXhhbXBsZS9leGFtcGxlL2V4YW1wbGUuaHRtbA==",
   "br_related_rid":"Rmjvgqrlzkun3g4rv04vl-m1,i1,c1,uf",
   "br_related_rid_tag":"<script type=\"text/javascript\">var br_related_rid = \"Rmjvgqrlzkun3g4rv04vl-m1,i1,c1,uf\";<\/script>",
   "related-item":[ 
      { 
         "anchor":"Covergirl pressed powder",
         "url":"/covergirl-pressed-powder-150-creamy-beige.html"
      }
   ],
   "more-results":[ 
      { 
         "image":"https://www.example.com/media/catalog/product/cache/image/700x700/e9c3970ab036de70892d86c6d221abfe/d/i/disney_pixar_cars_3_10-inch_lightning_mcqueen_vehicle.jpg",
         "description":"Disney Pixar Cars 3 10.5-Inch Lightning McQueen Vehicle",
         "attributes":[ 
            { 
               "value":"29412",
               "key":"product_id"
            }
         ],
         "title":"Disney Pixar Cars 3 10.5-Inch Lightning McQueen Vehicle",
         "short-description":"Disney Pixar Cars 3 10.5-Inch Lightning McQueen Vehicle",
         "url":"/disney-pixar-cars-3-10-5-inch-lightning-mcqueen-vehicle.html"
      }
   ]
}

Response processing

 

Full example response

{ 
   "related-category":[ 
      { 
         "anchor":"Pain Relief",
         "url":"/health/medicine-cabinet/pain-relief.html"
      },
      { 
         "anchor":"For Him",
         "url":"/holidays/stocking-stuffers/for-him.html"
      },
      { 
         "anchor":"Christmas Trees",
         "url":"/holidays/trim-the-tree/christmas-trees.html"
      },
      { 
         "anchor":"Kitchen Appliances",
         "url":"/household/kitchen-dining/kitchen-appliances.html"
      },
      { 
         "anchor":"Party Accessories",
         "url":"/party-occasions/party-accessories.html"
      }
   ],
   "br_iuid":"ZXhhbXBsZS5jb20vZXhhbXBsZS9leGFtcGxlL2V4YW1wbGUuaHRtbA==",
   "br_related_rid":"Rmjvgqrlzkun3g4rv04vl-m1,i1,c1,uf",
   "br_related_rid_tag":"<script type=\"text/javascript\">var br_related_rid = \"Rmjvgqrlzkun3g4rv04vl-m1,i1,c1,uf\";<\/script>",
   "related-item":[ 
      { 
         "anchor":"Covergirl pressed powder",
         "url":"/covergirl-pressed-powder-150-creamy-beige.html"
      },
      { 
         "anchor":"hanes-men-s-comfortsoftr",
         "url":"/hanes-men-s-comfortsoftr-white-crewneck-t-shirt-3-pack.html"
      },
      { 
         "anchor":"6 volt lantern",
         "url":"/rayovac-6-volt-lantern-assorted-colors.html"
      },
      { 
         "anchor":"Cherry Sours",
         "url":"/sweet-smiles-cherry-sours-7-oz-bag.html"
      }
   ],
   "more-results":[ 
      { 
         "image":"https://www.example.com/media/catalog/product/cache/image/700x700/e9c3970ab036de70892d86c6d221abfe/d/i/disney_pixar_cars_3_10-inch_lightning_mcqueen_vehicle.jpg",
         "description":"Disney Pixar Cars 3 10.5-Inch Lightning McQueen Vehicle",
         "attributes":[ 
            { 
               "value":"29412",
               "key":"product_id"
            }
         ],
         "title":"Disney Pixar Cars 3 10.5-Inch Lightning McQueen Vehicle",
         "short-description":"Disney Pixar Cars 3 10.5-Inch Lightning McQueen Vehicle",
         "url":"/disney-pixar-cars-3-10-5-inch-lightning-mcqueen-vehicle.html"
      },
      { 
         "image":"https://www.example.com/media/catalog/product/cache/image/700x700/e9c3970ab036de70892d86c6d221abfe/e/5/e53f15a1-00bb.jpg",
         "description":"description for rayovac lantern - not actual description but placeholder only",
         "attributes":[ 
            { 
               "value":"14711",
               "key":"product_id"
            }
         ],
         "title":"hanes-men-s-comfortsoftr",
         "short-description":"description for rayovac lantern - not actual description",
         "url":"/hanes-men-s-comfortsoftr-white-crewneck-t-shirt-3-pack.html"
      },
      { 
         "image":"https://www.example.com/media/catalog/product/cache/image/700x700/e9c3970ab036de70892d86c6d221abfe/e/5/e53f15a1-00bb.jpg",
         "description":"description for rayovac lantern - not actual description but placeholder only",
         "attributes":[ 
            { 
               "value":"29384",
               "key":"product_id"
            }
         ],
         "title":"Rayovac 6 Volt Lantern - Assorted Colors",
         "short-description":"description for rayovac lantern - not actual description",
         "url":"/rayovac-6-volt-lantern-assorted-colors.html"
      }
   ]
}

 

JSON Schema

{
  "$id": "br_fetch_widget_response",
  "type": "object",
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "br_iuid": {
      "$id": "/properties/br_iuid",
      "type": "string",
      "title": "The Br_iuid Schema ",
      "default": "",
      "examples": [
        "aHR0cHM6Ly93d3cuYmFybmVzYW5kbm9ibGUuY29tL3cvZGVhci1yZWFkZXItbWFyeS1vY29ubmVsbC8xMTIzMzQ0NTI4"
      ]
    },
    "more-results": {
      "$id": "/properties/more-results",
      "type": "array",
      "items": {
        "$id": "/properties/more-results/items",
        "type": "object",
        "properties": {
          "title": {
            "$id": "/properties/more-results/items/properties/title",
            "type": "string",
            "title": "The Title Schema ",
            "default": "",
            "examples": [
              "The Blackwell City Reader / Edition 2"
            ]
          },
          "description": {
            "$id": "/properties/more-results/items/properties/description",
            "type": "string",
            "title": "The Description Schema ",
            "default": "",
            "examples": [
              "Updated to reflect the most current thinking on urban studies, The Blackwell City Reader, Second Edition features a comprehensive selection of multidisciplinary readings relating to the analysis and experience of global cities. Includes new sections of materialities and mobilities to ..."
            ]
          },
          "short-description": {
            "$id": "/properties/more-results/items/properties/short-description",
            "type": "string",
            "title": "The Short-description Schema ",
            "default": "",
            "examples": [
              "Updated to reflect the most current thinking on urban studies, The Blackwell City Reader, Second"
            ]
          },
          "image": {
            "$id": "/properties/more-results/items/properties/image",
            "type": "string",
            "title": "The Image Schema ",
            "default": "",
            "examples": [
              "http://prodimage.images-bn.com/pimages/9781405189828_p0_v1_s550x406.jpg"
            ]
          },
          "attributes": {
            "$id": "/properties/more-results/items/properties/attributes",
            "type": "array",
            "items": {
              "$id": "/properties/more-results/items/properties/attributes/items",
              "type": "object",
              "properties": {
                "key": {
                  "$id": "/properties/more-results/items/properties/attributes/items/properties/key",
                  "type": "string",
                  "title": "The Key Schema ",
                  "default": "",
                  "examples": [
                    "rp_url"
                  ]
                },
                "value": {
                  "$id": "/properties/more-results/items/properties/attributes/items/properties/value",
                  "type": "string",
                  "title": "The Value Schema ",
                  "default": "",
                  "examples": [
                    "https://www.example.com/w/blackwell-city-reader-gary-bridge/1101189048?ean=9781405189828"
                  ]
                }
              }
            }
          },
          "url": {
            "$id": "/properties/more-results/items/properties/url",
            "type": "string",
            "title": "The Url Schema ",
            "default": "",
            "examples": [
              "https://www.example.com/w/blackwell-city-reader-gary-bridge/1101189048"
            ]
          }
        }
      }
    },
    "br_related_rid": {
      "$id": "/properties/br_related_rid",
      "type": "string",
      "title": "The Br_related_rid Schema ",
      "default": "",
      "examples": [
        "R66u1us1dqgm1sg7r1ymm-r1,m1,uf"
      ]
    },
    "related-category": {
      "$id": "/properties/related-category",
      "type": "array",
      "items": {
        "$id": "/properties/related-category/items",
        "type": "object",
        "properties": {
          "url": {
            "$id": "/properties/related-category/items/properties/url",
            "type": "string",
            "title": "The Url Schema ",
            "default": "",
            "examples": [
              "/w/classical-chinese-reader-a-d-syrokomla-stefanowska/1125352801"
            ]
          },
          "anchor": {
            "$id": "/properties/related-category/items/properties/anchor",
            "type": "string",
            "title": "The Anchor Schema ",
            "default": "",
            "examples": [
              "classical chinese reader edition 1"
            ]
          }
        }
      }
    },
    "related-item": {
      "$id": "/properties/related-item",
      "type": "array",
      "items": {
        "$id": "/properties/related-item/items",
        "type": "object",
        "properties": {
          "url": {
            "$id": "/properties/related-item/items/properties/url",
            "type": "string",
            "title": "The Url Schema ",
            "default": "",
            "examples": [
              "/w/classical-chinese-reader-a-d-syrokomla-stefanowska/1125352801"
            ]
          },
          "anchor": {
            "$id": "/properties/related-item/items/properties/anchor",
            "type": "string",
            "title": "The Anchor Schema ",
            "default": "",
            "examples": [
              "classical chinese reader edition 1"
            ]
          }
        }
      }
    },
    "br_related_rid_tag": {
      "$id": "/properties/br_related_rid_tag",
      "type": "string",
      "title": "The Br_related_rid_tag Schema ",
      "default": "",
      "examples": [
        "<script type=\"text/javascript\">var br_related_rid = \"R66u1us1dqgm1sg7r1ymm-r1,m1,uf\";</script>"
      ]
    }
  }
}    
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?