Skip to main content
RichRelevance

RecsForPlacementContext API

Note:  This API is currently limited to specific customers. Please see your RR team if you might want to use this API.

Details

This API in runtime server provides a mechanism to inject force strategies per placement at the moment, but the context can be enhanced later on. Right now, the recsForPlacements API can allow multiple placements in the same call but the context (parameters) sent are shared across all the target placements. 

This can be considered as a limitation by some since different context for different placements is not allowed. The recsForPlacementContext API is the first step to overcome that limitation. It accepts all of the query parameters as recsForPlacement API. It also accepts a context, which can be defined per placement.

The  difference between recsForPlacements and recsForPlacementsContext API:

recsForPlacements

recsForplacementsContext

GET api call POST api call
accepts query parameters documented

accepts query parameters document in recsForPlacements +

a POST body (placement context)

Parameters

Parameter Description
filterAtr passes attribute and value, list is or'd
   

Exceptions

Exception Condition
ArgumentNullException message is null.

Examples

Example 1:

http://qa.richrelevance.com/rrserver/api/rrPlatform/recsForPlacementsContext?apiClientKey=0503a7f4357b2f36&apiKey=45a98cdf34a56c26&placements=item_page.recsmiddle|item_page.rr1&l=1&sessionId=chirag12345&productId=88640

{   
    "placementContextInfo" : [
        {
        "placementName" :"item_page.recsmiddle",
        "placementConfig" : {
            "strategyConfig": {
                "strategies" : ["ViewedPurchased","ClickEV", "CategoryTopSellers"],
                "reorder" : false
            },
            "categorySeed" : "electronics",
            "filterConfig" : {
                "includeProductsMatchingFilters" : false,
                "categoryFilters" : ["video"],
                "minPriceFilter": null,
                "maxPriceFilter" : 5000,
                "attributeInfo" : {
                    "productsMatchAllAttributes" : false,
                    "attributeConfigs" : [
                        {
                            "attributeName" : "prime",
                            "attributeValues" : ["false"]
                        },
                        {
                            "attributeName" : "Clearance",
                            "attributeValues" : ["N"]
                        }
                    ]
                }
            },
            "productIds" : ["15847591"]
         }
       }
    ],
    "enableStrategyDuplication" : false
}

Here, client can send multiple placement objects.

Note : placement name passed in the request must be same as placementName mentioned in the post body.

In this example, we send the request for 2 placements : 

  • item_page.recsmiddle
  • item_page.rr1. 

But in the post body, we only defined "recsmiddle". So, for recsmiddle placement, we will force the strategies mentioned but for "item_page.rr1" the default pipeline will work (no force strategy, since we didn't pass any overriding context).

POST Body object 

  • placementContextInfo: a list which will hold information for each placement such as placement name, strategies to be run for that placement, category seed, different filters etc.
  • enableStrategyDuplication: Default=false. When set allows a strategy to be played multiple times on a particular page for the different placements.
  • placementName: name of the placement as specified in the request.
  • placementConfig : object which can hold different (overriding) configurations for this placement. (currently we just support strategyConfig)
  • strategyConfig: object which consists of overriding strategy configurations
  • strategies : a list of strategies which will be forced run, meaning these strategies will run first before any Experience Optimizer (XO) selected strategy or strategy rules preferred strategies. The client can pass a backfilled strategy in the list. If none of the strategies specified in the list return or satisfy recommendations after filtering, the call will fallback to strategies preferred in strategy rules targeting the given placement and then XO selected strategies from the strategies enabled for the given page type.

Fall back order:

  1. Request strategies defined (strategies listed within the API call)
  2. Strategies preferred within strategy rules targeting the given placement
  3. Experience Optimizer selected strategies based on those that are enabled for the page type in question
  • reorder : Default=false. If the client specifies reorder to be true, that would mean the client wants our machine learning algorithms (XO) to run and reorder the strategies list provided. The default for the recsForPlacementContext API is false. In this case, the client must provide strategies in the proper order. 
  • categorySeed:  the seed category to be used by the placement.
  • filterConfig: Filters to be applied to the items in the response for the given placement.
    • minPriceFilter: 579 (region price, sale price or if no sale price then list price)

    • maxPriceFilter: 1080 (region price, sale price or if no sale price then list price)

    • categoryFilter: 487553 (products that have one or more categories)

    • includeProductsMatchingFilters: True or False; default is true

      • ​​Applied for attributeConfigs, categoryFilter, minPriceFilter, maxPriceFilter

      • True means it is an inclusive filter i.e. only recommend products that match the filter. Ex: Only return products that belong to category 487553.

      • False means do not recommend products that match the filter. Ex: Do not return products that belong to category 487553.

  • attributeInfo: Holds the information about the different attributes and how they should be applied.
    • productsMatchAllAttributes: Default=true. When set, keeps only those products which have all the attributes as mentioned in the attributeConfigs. If not set, keeps only those products which have atleast one attribute of attributeConfigs.
    • attributeConfigs: A list of different attribute name and value which the recommended products should satisfy.
  • productIds: list of productIds which is utilized by the product seeded strategies such as ClickCP.

Example Response

{
  "rcs": "eF5j4cotK8lM4TMzsNA11DVkKU32MEkyBAJjM11jYzMzXRNTozRdA0sgYZxiammQaGJmZmaaDABuTQ0O",
  "placements": [
    {
      "htmlElementId": "home_page_0",
      "placementType": "home_page",
      "strategyMessage": "Shop Top Sellers",
      "html": "",
      "placement": "home_page.rr1",
      "recommendedProducts": [
        {
          "clickURL": "https://integration.richrelevance.com/rrserver/apiclick?a=showcaseparent&cak=776cdd80331919e7&ct=http%3A%2F%2Flabs.richrelevance.com%2Fstorre%2Fcatalog%2Fproduct%2Fview%2Fsku%2F22127002&vg=4b121136-3366-452f-092f-3d590a46665c&stid=126&pti=9&pa=11339&pos=0&p=22127002&channelId=776cdd80331919e7&s=827ccb0eea8a706c4c34a16891f84e7b&u=12345&mvtId=-1&mvtTs=1529712166361",
          "regionPriceDescription": "",
          "salePriceRangeCents": [
            1,
            1
          ],
          "rating": 3.884,
          "numReviews": 0,
          "priceRangeCents": [
            1,
            1
          ],
          "categoryIds": [
            "Electronics",
            "Electronics.Computers",
            "Electronics.Computers.Tablet PCs"
          ],
          "clickTrackingURL": "https://integration.richrelevance.com/rrserver/apiclick?a=showcaseparent&cak=776cdd80331919e7&vg=4b121136-3366-452f-092f-3d590a46665c&stid=126&pti=9&pa=11339&pos=0&p=22127002&channelId=776cdd80331919e7&s=827ccb0eea8a706c4c34a16891f84e7b&u=12345&mvtId=-1&mvtTs=1529712166361",
          "salePriceCents": 1,
          "regionalProductSku": "22127002",
          "imageURL": "http://labs.richrelevance.com/storre/media/catalog/product/n/e/nextbook-7quot-tablet-with-8gb-memory-with-google-mobile-services-73fbdb1640b18e99695aa87c7da712f5.jpg",
          "name": "\"Nextbook 7\\\" Tablet with 8GB Memory with Google Mobile Services\"",
          "genre": "default",
          "isRecommendable": true,
          "priceCents": 6900,
          "attributes": {
            "MktplcInd": [
              "W"
            ],
            "Clearance": [
              "N"
            ],
            "97CentShipping": [
              "N"
            ],
            "Rollback": [
              "N"
            ],
            "Online": [
              "Y"
            ],
            "ListPrice": [
              "79"
            ],
            "AddToCart": [
              "Y"
            ],
            "IsReducedPrice": [
              "N"
            ],
            "IsSubmap": [
              "N"
            ],
            "S2S": [
              "Y"
            ]
          },
          "id": "22127002",
          "categories": [
            {
              "hasChildren": false,
              "name": "Electronics",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics",
              "isActive": false
            },
            {
              "hasChildren": false,
              "name": "Computers",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics.Computers",
              "isActive": false
            },
            {
              "hasChildren": false,
              "name": "Tablet PCs",
              "childCategories": [],
              "ancestorCategories": [],
              "id": "Electronics.Computers.Tablet PCs",
              "isActive": false
            }
          ],
          "productURL": "http://labs.richrelevance.com/storre/catalog/product/view/sku/22127002",
          "brand": "Nextbook"
        }
      ]
    }
  ],
  "viewGuid": "4b121136-3366-452f-092f-3d590a46665c",
  "status": "ok"
}

Example 2:

http://localhost:8101/rrserver/api/rrPlatform/recsForPlacementsContext?apiClientKey=0503a7f4357b2f36&apiKey=45a98cdf34a56c26&placements=category_page.recsbottom&sessionId=7FzEGpX7iqeNZnWw9hNR6Jegy1kVCh11&rcs=eF4FwbERgCAQBMCEyF7O8eDgoQPb4EFnDMzU-t0Ny_0911yzIphF1labpY0oCWB4xy6fpk7BhxvUzwOmRPSS64gclJcfbskRrQ&l=1&pref=
https://www.build.com/bathroom/c108412&c=976
Body:

[
    {
    "placementName" :"category_page.recsbottom",
    "placementConfig" : {
        "strategyConfig": {
            "strategies" : [ "CategoryTopProducts","CategoryTopSellers"]
        },
        "categorySeed" : "889",
        "filterConfig" : {
            "includeProductsMatchingFilters" : true,
            "categoryFilters" : ["889-506438", "508606-516708-508608"],
            "minPriceFilter": null,
            "maxPriceFilter" : 2000,
            "attributeConfigs" : [
                    {
                        "attributeName" : "gender",
                        "attributeValues" : ["female"]
                    },
                    {
                        "attributeName" : "is_savings_constant",
                        "attributeValues" : ["true"]
                    }
                ]
        }
     }
   }
]

Considerations

Advanced Merchandising rules always run first before any strategy (customer defined or out of the box strategy) in the RichRelevance system. If Advanced Merchandising rules are targeting a placement and the placement is specified in the request, the rules fulfill the placement requirements, then  Advanced merchandising recommendations will be returned, ignoring this context passed. The client needs to make sure no Advanced Merchandising rules are targeting the same placement. 

  • Was this article helpful?