Services

Last updated
Save as PDF

Documentation of Services for Carnival

post /runtime/v1/recommend/itemPage/{productId}

Get recommendations for item page.

URI Parameters

productId: required (string

Request

Response

Request:

Body

Media type: application/json

Type: object

Properties

apiClientKey: required (string)
The api client assigned for the client specific application.
apiKey: required (string)
The api key of the merchant.
sessionId: (string)
The session id assigned to the request by the merchant.
user: (object)
All the user specific information that can be provided for the request
- userId: (string)
  The merchant defined identifier for the user.
- userAttributes: (array of UserAttribute)
  The attributes of the user that merchant can provide.
  
  Items: UserAttribute
  - attributeName: required (string)
    The name of the user attribute.
  - attributeValue: (array of )
    The value of the user attribute.
- segments: (array of string)
  All the segments a user might belong to.

userAgent: required (string)

The user agent string making the request

Example:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36

ipAddress: (string)
The public ip address of the originating request.
localizationContext: (object)
The localization context of the request.
- region: (string)
  The merchant defined region from which the request originated. It must match the regions provided in the feed by the merchant.
- language: (string)
  The merchant defined language code of the request. It must match the language codes in the feed provided by the merchant.
- currency: (string)
  The currency code for the request. It mush match the currency codes in the feed provided by the merchant.
placements: (array of string)
The list of the all the placements for which the recommendations were requested.
channelId: required (string)
The channel of the request.
rrUserGuid: (string)
The user id assigned to the request by Rich Relevance.
mvtId: (number)
Id to recognise the MVT split. Required to run MVT tests.
treatmentId: (number)
The id to force an MVT treatment.

Example:

{
  "apiKey": "649d16cbc8097816",
  "apiClientKey": "026658c7e431cdb5",
  "sessionId": "session1",
  "user": {
    "userId": "user123",
    "userAttributes": [
      {
        "attributeName": "hairColor"
      },
      {
        "attributeName": "age",
        "attributeValue": [
          "30"
        ]
      }
    ],
    "segments": [
      "under 30",
      "books"
    ]
  },
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36",
  "ipAddress": "64.125.118.246",
  "localizationContext": {
    "region": "r1",
    "language": "en-US",
    "currency": "$"
  },
  "placements": [
    "item_page.rr1",
    "item_page.horizontal"
  ],
  "channelId": "online",
  "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
  "mvtId": 123,
  "treatmentId": 125
}

Response:

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

requestId: required (string)
A unique request id assgined for each request by Rich Relevance.
viewGuid: required (string)
The view context id assigned by Rich Relevance.
mvt: required (array of MVTTreatment)
The MVT specific information for the request.

Items: MVTTreatment
- testId: required (number)
  The test identifier for MVT.
- treatmentId: required (number)
  The treatment identifier for MVT.
- treatmentName: required (string)
  The name of the treatment.
- control: required (boolean)
  Was the MVT part of the control.
rrUserGuid: required (string)
The user id assgned to the request by Rich Relevance.
responsePlacements: required (array of ResponsePlacement)
The recommendations for each placement fulfilled by the service for the request.
Items: ResponsePlacement
- placementName: required (string)
  The placement name for which the recommendation are returned.
- strategyMessage: required (string)
  The message attached to the strategy whose recommendations are being returned.
- strategyName: required (string)
  The name of the strategy whose recommendations are being returned.
- recommendedProducts: required (array of RecommendedProduct)
  The most relevant information of the products that are being recommended for the placement.
  
  Items: RecommendedProduct
  - productId: required (string)
    The unique identifier of the product being recommended.
  - productName: required (string)
    The name of the product being recommended.
  - productURL: required (string)
    The link on the merchant's website for the product.
  - imageURL: required (string)
    The location to the image of the product.
  - price: required (integer)
    The price of the product in cents.
  - priceRange: required (object)
    - minSalesPrice: required (integer)
      The minimum sales price of the product in cents.
    - maxSalesPrice: required (integer)
      The maximum sales price of the prodcut in cents.
  - brand: required (string)
    The brand of the product.
  - categories: required (array of ProductCategories)
    The categories to which a product belongs.
    
    Items: ProductCategories
    - categoryId: required (string)
      The identifier for a merchant's category.
    - categoryName: required (string)
      The name of the category.
  - productAttributes: required (array of ProductAttributes)
    All the product attributes.
    
    Items: ProductAttributes
    - attributeName: required (string)
      The name of the product attribute.
    - attributeValues: required (array of )
      The value associated with the attribute name.
  - ratings: required (number)
    The ratings that the product has received.
  - reviews: required (integer)
    The number of reviews that the product has received.
  - clickTrackingURL: required (string)
    The URL to track a click on the product by a Rich Relevance service.
unFulfilledPlacements: required (array of UnFulfilledPlacement)
The placements for which the recommendations are not being generated.

Items: UnFulfilledPlacement
- placementName: required (string)
  The name of the placement for which the recommendations are not returned.
- reason: required (string)
  The reason why the recommendations were not returned for the placement.

Example:

{
  "requestId": "request123",
  "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
  "viewGuid": "792b640b-8b56-4e8b-5249-0856340e99ce",
  "mvt": [
    {
      "testId": 12343545,
      "treatmentId": 123435454,
      "treatmentName": "TestTreatment",
      "control": true
    }
  ],
  "responsePlacements": [
    {
      "placementName": "item_page.rr1",
      "strategyMessage": "People who viewed this also viewed.",
      "strategyName": "ClickCP",
      "recommendedProducts": [
        {
          "productId": "product123",
          "productName": "Product Name",
          "productURL": "http://www.merchant.com/en/ip/productName/6000138847418",
          "imageURL": "images/Thumbnails/806/396/806396.jpg",
          "price": 798,
          "priceRange": {
            "minSalesPrice": 798,
            "maxSalesPrice": 798
          },
          "brand": "brandName",
          "categories": [
            {
              "categoryId": "cat1",
              "categoryName": "category1"
            },
            {
              "categoryId": "cat2",
              "categoryName": "category2"
            }
          ],
          "productAttributes": [
            {
              "attributeName": "attribute1",
              "attributeValues": [
                "attrValue1, attrValue2"
              ]
            },
            {
              "attributeName": "attribute2",
              "attributeValues": [
                "attrValue3",
                "attrValue4"
              ]
            }
          ],
          "ratings": 3.5,
          "reviews": 100,
          "clickTrackingURL": "http://api.richrelevance.com/rrserver/apiclick?apiKey=649d16cbc8097816apiClientKey=026658c7e431cdb5&viewGuid=80014ed0-8f22-4f5b-8455-7f550aeba753&strategyId=8&placement=item_page.rr1&position=1&productId=product123&channelId=channel1&sessionId=session1&userId=user123"
        }
      ]
    }
  ],
  "unFulfilledPlacements": [
    {
      "placementName": "item_page.horizontal",
      "reason": "The requested placement does not exists."
    }
  ]
}

HTTP status code 400

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

HTTP status code 500

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

POST /runtime/v1/recommend/purchasePage/

Get recommendations for purchase page.

Request:

Body

Media type: application/json

Type: object

Properties

rrContext: required (object)
The context that can be provided to Rich Relevance to best serve a request.
- apiClientKey: required (string)
  The api client assigned for the client specific application.
- apiKey: required (string)
  The api key of the merchant.
- sessionId: (string)
  The session id assigned to the request by the merchant.
- user: (object)
  All the user specific information that can be provided for the request
  - userId: (string)
    The merchant defined identifier for the user.
  - userAttributes: (array of UserAttribute)
    The attributes of the user that merchant can provide.
    
    Items: UserAttribute
    - attributeName: required (string)
      The name of the user attribute.
    - attributeValue: (array of )
      The value of the user attribute.
  - segments: (array of string)
    All the segments a user might belong to.
- userAgent: required (string)
  The user agent string making the request
  Example:
```
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36
```
- ipAddress: (string)
  The public ip address of the originating request.
- localizationContext: (object)
  The localization context of the request.
  - region: (string)
    The merchant defined region from which the request originated. It must match the regions provided in the feed by the merchant.
  - language: (string)
    The merchant defined language code of the request. It must match the language codes in the feed provided by the merchant.
  - currency: (string)
    The currency code for the request. It mush match the currency codes in the feed provided by the merchant.
- placements: (array of string)
  The list of the all the placements for which the recommendations were requested.
- channelId: required (string)
  The channel of the request.
- rrUserGuid: (string)
  The user id assigned to the request by Rich Relevance.
- mvtId: (number)
  Id to recognise the MVT split. Required to run MVT tests.
- treatmentId: (number)
  The id to force an MVT treatment.
purchaseOrders: required (array of PurchaseOrder)
The information about the products purchased.

Items: PurchaseOrder
- orderId: (string)
  The purchase order number.
- productLineItems: required (array of ProductLineItem)
  The product purchased in the order.
  
  Items: ProductLineItem
  - productId: required (string)
    The product that was purchased.
  - quantity: required (integer)
    The number of units that were purchased.
  - priceCents: required (integer)
    The price of the product that was purchased.
  - sku: (string)
    The identifier of the SKU that was purchased if any.
- orderChannel: (string)
  The retail channel through which the product was purchased.
- emailHash: (string)
  The hash of the email address of the user.
- cardHash: (string)
  The hash of the credit card used for purchase.
- storeId: (string)
  The store in which the purchase was made.

Example:

{
  "rrContext": {
    "apiKey": "649d16cbc8097816",
    "apiClientKey": "026658c7e431cdb5",
    "sessionId": "session1",
    "user": {
      "userId": "user123",
      "userAttributes": [
        {
          "attributeName": "hairColor"
        },
        {
          "attributeName": "age",
          "attributeValue": [
            "30"
          ]
        }
      ],
      "segments": [
        "under 30",
        "books"
      ]
    },
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36",
    "ipAddress": "64.125.118.246",
    "localizationContext": {
      "region": "r1",
      "language": "en-US",
      "currency": "$"
    },
    "placements": [
      "purchase_page.rr1",
      "purchase_page.horizontal"
    ],
    "channelId": "online",
    "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
    "mvtId": 123,
    "treatmentId": 125
  },
  "purchaseOrders": [
    {
      "orderId": "order123",
      "productLineItems": [
        {
          "productId": "product345",
          "quantity": 2,
          "priceCents": 200,
          "sku": "sku3451"
        }
      ],
      "orderChannel": "store",
      "storeId": "sf94107",
      "emailHash": "d927ad81199aa7dcadfdb4e47b6dc694",
      "cardHash": "d927ad81199aa7dcadfdb4e47b6dc694"
    }
  ]
}

Response:

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

requestId: required (string)
A unique request id assgined for each request by Rich Relevance.
viewGuid: required (string)
The view context id assigned by Rich Relevance.
mvt: required (array of MVTTreatment)
The MVT specific information for the request.

Items: MVTTreatment
- testId: required (number)
  The test identifier for MVT.
- treatmentId: required (number)
  The treatment identifier for MVT.
- treatmentName: required (string)
  The name of the treatment.
- control: required (boolean)
  Was the MVT part of the control.
rrUserGuid: required (string)
The user id assgned to the request by Rich Relevance.
responsePlacements: required (array of ResponsePlacement)
The recommendations for each placement fulfilled by the service for the request.

Items: ResponsePlacement
- placementName: required (string)
  The placement name for which the recommendation are returned.
- strategyMessage: required (string)
  The message attached to the strategy whose recommendations are being returned.
- strategyName: required (string)
  The name of the strategy whose recommendations are being returned.
- recommendedProducts: required (array of RecommendedProduct)
  The most relevant information of the products that are being recommended for the placement.
  
  Items: RecommendedProduct
  - productId: required (string)
    The unique identifier of the product being recommended.
  - productName: required (string)
    The name of the product being recommended.
  - productURL: required (string)
    The link on the merchant's website for the product.
  - imageURL: required (string)
    The location to the image of the product.
  - price: required (integer)
    The price of the product in cents.
  - priceRange: required (object)
    - minSalesPrice: required (integer)
      The minimum sales price of the product in cents.
    - maxSalesPrice: required (integer)
      The maximum sales price of the prodcut in cents.
  - brand: required (string)
    The brand of the product.
  - categories: required (array of ProductCategories)
    The categories to which a product belongs.
    
    Items: ProductCategories
    - categoryId: required (string)
      The identifier for a merchant's category.
    - categoryName: required (string)
      The name of the category.
  - productAttributes: required (array of ProductAttributes)
    All the product attributes.
    
    Items: ProductAttributes
    - attributeName: required (string)
      The name of the product attribute.
    - attributeValues: required (array of )
      The value associated with the attribute name.
  - ratings: required (number)
    The ratings that the product has received.
  - reviews: required (integer)
    The number of reviews that the product has received.
  - clickTrackingURL: required (string)
    The URL to track a click on the product by a Rich Relevance service.
unFulfilledPlacements: required (array of UnFulfilledPlacement)
The placements for which the recommendations are not being generated.

Items: UnFulfilledPlacement
- placementName: required (string)
  The name of the placement for which the recommendations are not returned.
- reason: required (string)
  The reason why the recommendations were not returned for the placement.

Example:

{
  "requestId": "request123",
  "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
  "viewGuid": "792b640b-8b56-4e8b-5249-0856340e99ce",
  "mvt": [
    {
      "testId": 12343545,
      "treatmentId": 123435454,
      "treatmentName": "TestTreatment",
      "control": true
    }
  ],
  "responsePlacements": [
    {
      "placementName": "purchase_page.rr1",
      "strategyMessage": "People who viewed this also bought.",
      "strategyName": "PurchaseCP",
      "recommendedProducts": [
        {
          "productId": "product123",
          "productName": "Product Name",
          "productURL": "http://www.merchant.com/en/ip/productName/6000138847418",
          "imageURL": "images/Thumbnails/806/396/806396.jpg",
          "price": 798,
          "priceRange": {
            "minSalesPrice": 798,
            "maxSalesPrice": 798
          },
          "brand": "brandName",
          "categories": [
            {
              "categoryId": "cat1",
              "categoryName": "category1"
            },
            {
              "categoryId": "cat2",
              "categoryName": "category2"
            }
          ],
          "productAttributes": [
            {
              "attributeName": "attribute1",
              "attributeValues": [
                "attrValue1, attrValue2"
              ]
            },
            {
              "attributeName": "attribute2",
              "attributeValues": [
                "attrValue3",
                "attrValue4"
              ]
            }
          ],
          "ratings": 3.5,
          "reviews": 100,
          "clickTrackingURL": "http://api.richrelevance.com/rrserver/apiclick?apiKey=649d16cbc8097816apiClientKey=026658c7e431cdb5&viewGuid=80014ed0-8f22-4f5b-8455-7f550aeba753&strategyId=8&placement=item_page.rr1&position=1&productId=product123&channelId=channel1&sessionId=session1&userId=user123"
        }
      ]
    }
  ],
  "unFulfilledPlacements": [
    {
      "placementName": "purchase_page.horizontal",
      "reason": "The requested placement does not exists."
    }
  ]
}

HTTP status code 400

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

HTTP status code 500

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

POST /runtime/v1/recommend/categoryPage/{categoryId}

Get recommendations for category page.

URI Parameters

categoryId: required (string)

Request

Body

Media type: application/json

Type: object

Properties

apiClientKey: required (string)
The api client assigned for the client specific application.
apiKey: required (string)
The api key of the merchant.
sessionId: (string)
The session id assigned to the request by the merchant.
user: (object)
All the user specific information that can be provided for the request
- userId: (string)
  The merchant defined identifier for the user.
- userAttributes: (array of UserAttribute)
  The attributes of the user that merchant can provide.
  
  Items: UserAttribute
  - attributeName: required (string)
    The name of the user attribute.
  - attributeValue: (array of )
    The value of the user attribute.
- segments: (array of string)
  All the segments a user might belong to.

userAgent: required (string)

The user agent string making the request

Example:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36

ipAddress: (string)
The public ip address of the originating request.
localizationContext: (object)
The localization context of the request.
- region: (string)
  The merchant defined region from which the request originated. It must match the regions provided in the feed by the merchant.
- language: (string)
  The merchant defined language code of the request. It must match the language codes in the feed provided by the merchant.
- currency: (string)
  The currency code for the request. It mush match the currency codes in the feed provided by the merchant.
placements: (array of string)
The list of the all the placements for which the recommendations were requested.
channelId: required (string)
The channel of the request.
rrUserGuid: (string)
The user id assigned to the request by Rich Relevance.
mvtId: (number)
Id to recognise the MVT split. Required to run MVT tests.
treatmentId: (number)
The id to force an MVT treatment.

Example:

{
  "apiKey": "649d16cbc8097816",
  "apiClientKey": "026658c7e431cdb5",
  "sessionId": "session1",
  "user": {
    "userId": "user123",
    "userAttributes": [
      {
        "attributeName": "hairColor"
      },
      {
        "attributeName": "age",
        "attributeValue": [
          "30"
        ]
      }
    ],
    "segments": [
      "under 30",
      "books"
    ]
  },
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36",
  "ipAddress": "64.125.118.246",
  "localizationContext": {
    "region": "r1",
    "language": "en-US",
    "currency": "$"
  },
  "placements": [
    "category_page.rr1",
    "category_page.horizontal"
  ],
  "channelId": "online",
  "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
  "mvtId": 124,
  "treatmentId": 125
}

Response

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

requestId: required (string)
A unique request id assgined for each request by Rich Relevance.
viewGuid: required (string)
The view context id assigned by Rich Relevance.
mvt: required (array of MVTTreatment)
The MVT specific information for the request.

Items: MVTTreatment
- testId: required (number)
  The test identifier for MVT.
- treatmentId: required (number)
  The treatment identifier for MVT.
- treatmentName: required (string)
  The name of the treatment.
- control: required (boolean)
  Was the MVT part of the control.
rrUserGuid: required (string)
The user id assgned to the request by Rich Relevance.
responsePlacements: required (array of ResponsePlacement)
The recommendations for each placement fulfilled by the service for the request.

Items: ResponsePlacement
- placementName: required (string)
  The placement name for which the recommendation are returned.
- strategyMessage: required (string)
  The message attached to the strategy whose recommendations are being returned.
- strategyName: required (string)
  The name of the strategy whose recommendations are being returned.
- recommendedProducts: required (array of RecommendedProduct)
  The most relevant information of the products that are being recommended for the placement.
  
  Items: RecommendedProduct
  - productId: required (string)
    The unique identifier of the product being recommended.
  - productName: required (string)
    The name of the product being recommended.
  - productURL: required (string)
    The link on the merchant's website for the product.
  - imageURL: required (string)
    The location to the image of the product.
  - price: required (integer)
    The price of the product in cents.
  - priceRange: required (object)
    - minSalesPrice: required (integer)
      The minimum sales price of the product in cents.
    - maxSalesPrice: required (integer)
      The maximum sales price of the prodcut in cents.
  - brand: required (string)
    The brand of the product.
  - categories: required (array of ProductCategories)
    The categories to which a product belongs.
    
    Items: ProductCategories
    - categoryId: required (string)
      The identifier for a merchant's category.
    - categoryName: required (string)
      The name of the category.
  - productAttributes: required (array of ProductAttributes)
    All the product attributes.
    
    Items: ProductAttributes
    - attributeName: required (string)
      The name of the product attribute.
    - attributeValues: required (array of )
      The value associated with the attribute name.
  - ratings: required (number)
    The ratings that the product has received.
  - reviews: required (integer)
    The number of reviews that the product has received.
  - clickTrackingURL: required (string)
    The URL to track a click on the product by a Rich Relevance service.
unFulfilledPlacements: required (array of UnFulfilledPlacement)
The placements for which the recommendations are not being generated.

Items: UnFulfilledPlacement
- placementName: required (string)
  The name of the placement for which the recommendations are not returned.
- reason: required (string)
  The reason why the recommendations were not returned for the placement.

Example:

{
  "requestId": "request123",
  "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
  "viewGuid": "792b640b-8b56-4e8b-5249-0856340e99ce",
  "mvt": [
    {
      "testId": 12343545,
      "treatmentId": 123435454,
      "treatmentName": "TestTreatment",
      "control": true
    }
  ],
  "responsePlacements": [
    {
      "placementName": "category_page.rr1",
      "strategyMessage": "Top sellers in category.",
      "strategyName": "CategoryTopSellers",
      "recommendedProducts": [
        {
          "productId": "product123",
          "productName": "Product Name",
          "productURL": "http://www.merchant.com/en/ip/productName/6000138847418",
          "imageURL": "images/Thumbnails/806/396/806396.jpg",
          "price": 798,
          "priceRange": {
            "minSalesPrice": 798,
            "maxSalesPrice": 798
          },
          "brand": "brandName",
          "categories": [
            {
              "categoryId": "cat1",
              "categoryName": "category1"
            },
            {
              "categoryId": "cat2",
              "categoryName": "category2"
            }
          ],
          "productAttributes": [
            {
              "attributeName": "attribute1",
              "attributeValues": [
                "attrValue1, attrValue2"
              ]
            },
            {
              "attributeName": "attribute2",
              "attributeValues": [
                "attrValue3",
                "attrValue4"
              ]
            }
          ],
          "ratings": 3.5,
          "reviews": 100,
          "clickTrackingURL": "http://api.richrelevance.com/rrserver/apiclick?apiKey=649d16cbc8097816apiClientKey=026658c7e431cdb5&viewGuid=80014ed0-8f22-4f5b-8455-7f550aeba753&strategyId=8&placement=item_page.rr1&position=1&productId=product123&channelId=channel1&sessionId=session1&userId=user123"
        }
      ]
    }
  ],
  "unFulfilledPlacements": [
    {
      "placementName": "category_page.horizontal",
      "reason": "The requested placement does not exists."
    }
  ]
}

HTTP status code 400

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

HTTP status code 500

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

POST /runtime/v1/recommend/addToCartPage/

Get recommendations for add to cart page.

Request

Body

Media type: application/json

Type: object

Properties

rrContext: required (object)
The context that can be provided to Rich Relevance to best serve a request.
- apiClientKey: required (string)
  The api client assigned for the client specific application.
- apiKey: required (string)
  The api key of the merchant.
- sessionId: (string)
  The session id assigned to the request by the merchant.
- user: (object)
  All the user specific information that can be provided for the request
  - userId: (string)
    The merchant defined identifier for the user.
  - userAttributes: (array of UserAttribute)
    The attributes of the user that merchant can provide.
    
    Items: UserAttribute
    - attributeName: required (string)
      The name of the user attribute.
    - attributeValue: (array of )
      The value of the user attribute.
  - segments: (array of string)
    All the segments a user might belong to.
- userAgent: required (string)
  The user agent string making the request
  
  Example:
```
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36
```
- ipAddress: (string)
  The public ip address of the originating request.
- localizationContext: (object)
  The localization context of the request.
  - region: (string)
    The merchant defined region from which the request originated. It must match the regions provided in the feed by the merchant.
  - language: (string)
    The merchant defined language code of the request. It must match the language codes in the feed provided by the merchant.
  - currency: (string)
    The currency code for the request. It mush match the currency codes in the feed provided by the merchant.
- placements: (array of string)
  The list of the all the placements for which the recommendations were requested.
- channelId: required (string)
  The channel of the request.
- rrUserGuid: (string)
  The user id assigned to the request by Rich Relevance.
- mvtId: (number)
  Id to recognise the MVT split. Required to run MVT tests.
- treatmentId: (number)
  The id to force an MVT treatment.
productLineItems: required (array of ProductLineItem)
The information of the products added to cart or in cart.

Items: ProductLineItem
- productId: required (string)
  The product that was purchased.
- quantity: required (integer)
  The number of units that were purchased.
- priceCents: required (integer)
  The price of the product that was purchased.
- sku: (string)
  The identifier of the SKU that was purchased if any.

Example:

{
  "rrContext": {
    "apiKey": "649d16cbc8097816",
    "apiClientKey": "026658c7e431cdb5",
    "sessionId": "session1",
    "user": {
      "userId": "user123",
      "userAttributes": [
        {
          "attributeName": "hairColor"
        },
        {
          "attributeName": "age",
          "attributeValue": [
            "30"
          ]
        }
      ],
      "segments": [
        "under 30",
        "books"
      ]
    },
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36",
    "ipAddress": "64.125.118.246",
    "localizationContext": {
      "region": "r1",
      "language": "en-US",
      "currency": "$"
    },
    "placements": [
      "add_to_cart_page.rr1",
      "add_to_cart_page.horizontal"
    ],
    "channelId": "online",
    "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
    "mvtId": 123,
    "treatmentId": 125
  },
  "productLineItems": [
    {
      "productId": "product345",
      "quantity": 2,
      "priceCents": 200,
      "sku": "sku3451"
    }
  ]
}

Response:

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

requestId: required (string)
A unique request id assgined for each request by Rich Relevance.
viewGuid: required (string)
The view context id assigned by Rich Relevance.
mvt: required (array of MVTTreatment)
The MVT specific information for the request.

Items: MVTTreatment
- testId: required (number)
  The test identifier for MVT.
- treatmentId: required (number)
  The treatment identifier for MVT.
- treatmentName: required (string)
  The name of the treatment.
- control: required (boolean)
  Was the MVT part of the control.
rrUserGuid: required (string)
The user id assgned to the request by Rich Relevance.
responsePlacements: required (array of ResponsePlacement)
The recommendations for each placement fulfilled by the service for the request.

Items: ResponsePlacement
- placementName: required (string)
  The placement name for which the recommendation are returned.
- strategyMessage: required (string)
  The message attached to the strategy whose recommendations are being returned.
- strategyName: required (string)
  The name of the strategy whose recommendations are being returned.
- recommendedProducts: required (array of RecommendedProduct)
  The most relevant information of the products that are being recommended for the placement.
  
  Items: RecommendedProduct
  - productId: required (string)
    The unique identifier of the product being recommended.
  - productName: required (string)
    The name of the product being recommended.
  - productURL: required (string)
    The link on the merchant's website for the product.
  - imageURL: required (string)
    The location to the image of the product.
  - price: required (integer)
    The price of the product in cents.
  - priceRange: required (object)
    - minSalesPrice: required (integer)
      The minimum sales price of the product in cents.
    - maxSalesPrice: required (integer)
      The maximum sales price of the prodcut in cents.
  - brand: required (string)
    The brand of the product.
  - categories: required (array of ProductCategories)
    The categories to which a product belongs.
    
    Items: ProductCategories
    - categoryId: required (string)
      The identifier for a merchant's category.
    - categoryName: required (string)
      The name of the category.
  - productAttributes: required (array of ProductAttributes)
    All the product attributes.
    
    Items: ProductAttributes
    - attributeName: required (string)
      The name of the product attribute.
    - attributeValues: required (array of )
      The value associated with the attribute name.
  - ratings: required (number)
    The ratings that the product has received.
  - reviews: required (integer)
    The number of reviews that the product has received.
  - clickTrackingURL: required (string)
    The URL to track a click on the product by a Rich Relevance service.
unFulfilledPlacements: required (array of UnFulfilledPlacement)
The placements for which the recommendations are not being generated.

Items: UnFulfilledPlacement
- placementName: required (string)
  The name of the placement for which the recommendations are not returned.
- reason: required (string)
  The reason why the recommendations were not returned for the placement.

Example:

{
  "requestId": "request123",
  "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
  "viewGuid": "792b640b-8b56-4e8b-5249-0856340e99ce",
  "mvt": [
    {
      "testId": 12343545,
      "treatmentId": 123435454,
      "treatmentName": "TestTreatment",
      "control": true
    }
  ],
  "responsePlacements": [
    {
      "placementName": "add_to_cart_page.rr1",
      "strategyMessage": "People who viewed this also viewed.",
      "strategyName": "ClickCP",
      "recommendedProducts": [
        {
          "productId": "product123",
          "productName": "Product Name",
          "productURL": "http://www.merchant.com/en/ip/productName/6000138847418",
          "imageURL": "images/Thumbnails/806/396/806396.jpg",
          "price": 798,
          "priceRange": {
            "minSalesPrice": 798,
            "maxSalesPrice": 798
          },
          "brand": "brandName",
          "categories": [
            {
              "categoryId": "cat1",
              "categoryName": "category1"
            },
            {
              "categoryId": "cat2",
              "categoryName": "category2"
            }
          ],
          "productAttributes": [
            {
              "attributeName": "attribute1",
              "attributeValues": [
                "attrValue1, attrValue2"
              ]
            },
            {
              "attributeName": "attribute2",
              "attributeValues": [
                "attrValue3",
                "attrValue4"
              ]
            }
          ],
          "ratings": 3.5,
          "reviews": 100,
          "clickTrackingURL": "http://api.richrelevance.com/rrserver/apiclick?apiKey=649d16cbc8097816apiClientKey=026658c7e431cdb5&viewGuid=80014ed0-8f22-4f5b-8455-7f550aeba753&strategyId=8&placement=item_page.rr1&position=1&productId=product123&channelId=channel1&sessionId=session1&userId=user123"
        }
      ]
    }
  ],
  "unFulfilledPlacements": [
    {
      "placementName": "add_to_cart_page.horizontal",
      "reason": "The requested placement does not exists."
    }
  ]
}

HTTP status code 400

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

HTTP status code 500

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

POST /runtime/v1/recommend/searchPage/{searchTerm}

Get recommendations for search page.

URI Parameters

searchTerm: required (string)

Request:

Body

Media type: application/json

Type: object

Properties

apiClientKey: required (string)
The api client assigned for the client specific application.
apiKey: required (string)
The api key of the merchant.
sessionId: (string)
The session id assigned to the request by the merchant.
user: (object)
All the user specific information that can be provided for the request
- userId: (string)
  The merchant defined identifier for the user.
- userAttributes: (array of UserAttribute)
  The attributes of the user that merchant can provide.
  
  Items: UserAttribute
  - attributeName: required (string)
    The name of the user attribute.
  - attributeValue: (array of )
    The value of the user attribute.
- segments: (array of string)
  All the segments a user might belong to.

userAgent: required (string)

The user agent string making the request

Example:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36

ipAddress: (string)
The public ip address of the originating request.
localizationContext: (object)
The localization context of the request.
- region: (string)
  The merchant defined region from which the request originated. It must match the regions provided in the feed by the merchant.
- language: (string)
  The merchant defined language code of the request. It must match the language codes in the feed provided by the merchant.
- currency: (string)
  The currency code for the request. It mush match the currency codes in the feed provided by the merchant.
placements: (array of string)
The list of the all the placements for which the recommendations were requested.
channelId: required (string)
The channel of the request.
rrUserGuid: (string)
The user id assigned to the request by Rich Relevance.
mvtId: (number)
Id to recognise the MVT split. Required to run MVT tests.
treatmentId: (number)
The id to force an MVT treatment.

Example:

{
  "apiKey": "649d16cbc8097816",
  "apiClientKey": "026658c7e431cdb5",
  "sessionId": "session1",
  "user": {
    "userId": "user123",
    "userAttributes": [
      {
        "attributeName": "hairColor"
      },
      {
        "attributeName": "age",
        "attributeValue": [
          "30"
        ]
      }
    ],
    "segments": [
      "under 30",
      "books"
    ]
  },
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1944.0 Safari/537.36",
  "ipAddress": "64.125.118.246",
  "localizationContext": {
    "region": "r1",
    "language": "en-US",
    "currency": "$"
  },
  "placements": [
    "search_page.rr1",
    "search_page.horizontal"
  ],
  "channelId": "online",
  "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
  "mvtId": 123,
  "treatmentId": 125
}

Response:

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

requestId: required (string)
A unique request id assgined for each request by Rich Relevance.
viewGuid: required (string)
The view context id assigned by Rich Relevance.
mvt: required (array of MVTTreatment)
The MVT specific information for the request.

Items: MVTTreatment
- testId: required (number)
  The test identifier for MVT.
- treatmentId: required (number)
  The treatment identifier for MVT.
- treatmentName: required (string)
  The name of the treatment.
- control: required (boolean)
  Was the MVT part of the control.
rrUserGuid: required (string)
The user id assgned to the request by Rich Relevance.
responsePlacements: required (array of ResponsePlacement)
The recommendations for each placement fulfilled by the service for the request.

Items: ResponsePlacement
- placementName: required (string)
  The placement name for which the recommendation are returned.
- strategyMessage: required (string)
  The message attached to the strategy whose recommendations are being returned.
- strategyName: required (string)
  The name of the strategy whose recommendations are being returned.
- recommendedProducts: required (array of RecommendedProduct)
  The most relevant information of the products that are being recommended for the placement.
  
  Items: RecommendedProduct
  - productId: required (string)
    The unique identifier of the product being recommended.
  - productName: required (string)
    The name of the product being recommended.
  - productURL: required (string)
    The link on the merchant's website for the product.
  - imageURL: required (string)
    The location to the image of the product.
  - price: required (integer)
    The price of the product in cents.
  - priceRange: required (object)
    - minSalesPrice: required (integer)
      The minimum sales price of the product in cents.
    - maxSalesPrice: required (integer)
      The maximum sales price of the prodcut in cents.
  - brand: required (string)
    The brand of the product.
  - categories: required (array of ProductCategories)
    The categories to which a product belongs.
    
    Items: ProductCategories
    - categoryId: required (string)
      The identifier for a merchant's category.
    - categoryName: required (string)
      The name of the category.
  - productAttributes: required (array of ProductAttributes)
    All the product attributes.
    
    Items: ProductAttributes
    - attributeName: required (string)
      The name of the product attribute.
    - attributeValues: required (array of )
      The value associated with the attribute name.
  - ratings: required (number)
    The ratings that the product has received.
  - reviews: required (integer)
    The number of reviews that the product has received.
  - clickTrackingURL: required (string)
    The URL to track a click on the product by a Rich Relevance service.
unFulfilledPlacements: required (array of UnFulfilledPlacement)
The placements for which the recommendations are not being generated.

Items: UnFulfilledPlacement
- placementName: required (string)
  The name of the placement for which the recommendations are not returned.
- reason: required (string)
  The reason why the recommendations were not returned for the placement.

Example:

{
  "requestId": "request123",
  "rrUserGuid": "2694fbdf-c756-4a79-b7bf-a6560ac2ebd5",
  "viewGuid": "792b640b-8b56-4e8b-5249-0856340e99ce",
  "mvt": [
    {
      "testId": 12343545,
      "treatmentId": 123435454,
      "treatmentName": "TestTreatment",
      "control": true
    }
  ],
  "responsePlacements": [
    {
      "placementName": "add_to_cart.rr1",
      "strategyMessage": "People who viewed this also viewed.",
      "strategyName": "ClickCP",
      "recommendedProducts": [
        {
          "productId": "product123",
          "productName": "Product Name",
          "productURL": "http://www.merchant.com/en/ip/productName/6000138847418",
          "imageURL": "images/Thumbnails/806/396/806396.jpg",
          "price": 798,
          "priceRange": {
            "minSalesPrice": 798,
            "maxSalesPrice": 798
          },
          "brand": "brandName",
          "categories": [
            {
              "categoryId": "cat1",
              "categoryName": "category1"
            },
            {
              "categoryId": "cat2",
              "categoryName": "category2"
            }
          ],
          "productAttributes": [
            {
              "attributeName": "attribute1",
              "attributeValues": [
                "attrValue1, attrValue2"
              ]
            },
            {
              "attributeName": "attribute2",
              "attributeValues": [
                "attrValue3",
                "attrValue4"
              ]
            }
          ],
          "ratings": 3.5,
          "reviews": 100,
          "clickTrackingURL": "http://api.richrelevance.com/rrserver/apiclick?apiKey=649d16cbc8097816apiClientKey=026658c7e431cdb5&viewGuid=80014ed0-8f22-4f5b-8455-7f550aeba753&strategyId=8&placement=item_page.rr1&position=1&productId=product123&channelId=channel1&sessionId=session1&userId=user123"
        }
      ]
    }
  ],
  "unFulfilledPlacements": [
    {
      "placementName": "search_page.horizontal",
      "reason": "The requested placement does not exists."
    }
  ]
}

HTTP status code 400

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

HTTP status code 500

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

post /runtime/v1/recommend/click

Log a recommendation click. The merchant does not have create this request if they simply use the URL provided in the response. The parameter in the URL are listed below.

Request:

Query Parameters

apiKey: required (string)
The api key of the merchant.

Example:
```
649d16cbc8097816
```
apiClientKey: required (string)
The api client assigned for the client specific application.

Example:
```
026658c7e431cdb5
```
sessionId: required (string)
The id assigned to the device session.

Example:
```
session1
```
userId: required (string)
The id assigned to the user by the client

Example:
```
user123
```
channelId: required (string)
The channel id through which the click was made.

Example:
```
channel1
```
productId: required (string)
The product clicked on.

Example:
```
product123
```
position: required (integer)
The position of the product in the placement.

Example:
```
1
```
strategyId: required (integer)
Rich Relevance internal identifier for the strategy.

Example:
```
8
```
placement: required (string)
The placement on which the click happened.

Example:
```
item_page.rr1
```
viewGuid: required (string)
The view context id assigned by Rich Relevance.

Example:
```
80014ed0-8f22-4f5b-8455-7f550aeba753
```

Response:

HTTP status code 200

Body

Media type: application/json

Type: string

HTTP status code 400

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

HTTP status code 500

Body

Media type: application/json

Type: object

Properties

code: required (integer)
details: required (string)
message: required (string)
status: required (string)

post /runtime/v1/recommend/itemPage/{productId}

URI Parameters

Request:

Body

Properties

Example:

Example:

Response:

HTTP status code 200

Body

Media type: application/json

Type: object

Properties

Items: ResponsePlacement

Example:

HTTP status code 400

Body

Media type: application/json

Type: object

Properties

HTTP status code 500

Body

Media type: application/json

Type: object

Properties

POST /runtime/v1/recommend/purchasePage/

Request:

Body

Media type: application/json

Type: object

Properties

Example:

Response:

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 500

Body

POST /runtime/v1/recommend/categoryPage/{categoryId}

URI Parameters

Request

Body

Response

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 500

Body

POST /runtime/v1/recommend/addToCartPage/

Request

Body

Response:

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 500

Body

POST /runtime/v1/recommend/searchPage/{searchTerm}

URI Parameters

Request:

Body

Response:

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 500

Body

post /runtime/v1/recommend/click

Request:

Query Parameters

Response:

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 500