Skip to main content
RichRelevance

Ensemble AI Client API

  1. Last updated
  2. Save as PDF

 

This endpoint returns for ensembles (outfits/collections) for a given seed product.

URL

Production

Use this URL to request ensembles from your production environment.

https://recs.richrelevance.com/rrserver/api/rrPlatform/compositeOutfitRecs

Integration

Use this URL to request personalization from your QA, staging or development environment. This way, you can test changes without impacting your production environment.

https://integration.richrelevance.com/rrserver/api/rrPlatform/compositeOutfitRecs

Parameters

Note: Only call parameters that you need. Algonomy operates off a set of APIs that support many applications and clients concurrently. Algonomy may update and enhance these APIs at any time.

Note: All parameters are case sensitive.

Name Required/Optional Description

apiClientKey

Required

A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by Algonomy.

Example: apiClientKey=b0126f995ac848159d

apiKey

Required

A unique key that identifies the site. Each Algonomy client has a unique API key to separate data and traffic from other clients. This is provided by Algonomy.

Example: apiKey=4faeaf752ee40a0f

seed

Required

This should be a single product ID.

Example: seed= 345234

styloid

Optional

The style id is a unique identifier associated with a style created by Merchandiser in Ensemble AI UI.

includeDisabledStyles

Optional

true (or) false

Styles can be enabled or disabled once created. If this parameter is passed as true, then the API will respond with ensembles/outfits for disabled styles as well. If this parameter is not passed (or) passed as false, the outfits will be shown only from the styles that are enabled.

userId

Required when available

 

User ID. A unique string to identify each customer (user). All customer behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to Algonomy in other applications.

Example: userId=0982347

sessionId

Required

Identifies a single visit by a customer.  Sessions are used by behavioral models (to scope user behavior in a shopping session) and reporting metrics.

Example: sessionId=93484

 

rcs

Optional

Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response.

Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers.

Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API.

 

rid

Optional

Region ID. Must be consistent with the ID used in the product region feed.

Example: rid=Switzerland-France

 

Sample Requests

Get all ensembles across all styles that are enabled for a given seed product:

 

https://recs.richrelevance.com/rrserver/api/rrPlatform/compositeOutfitRecs?apiKey=XXXXXXX&apiClientKey=YYYYY&seed=123423&userId=64545454

Get all ensembles for a specific style for a given seed product:

 

https://recs.richrelevance.com/rrserver/api/rrPlatform/compositeOutfitRecs?apiKey=XXXXXXX&apiClientKey=YYYYY&seed=123423&userId=64545454&styleId=98080934

Get all ensembles across all styles (both enabled & disabled) for a given seed product:

 

https://recs.richrelevance.com/rrserver/api/rrPlatform/compositeOutfitRecs?apiKey=XXXXXXX&apiClientKey=YYYYY&seed=123423&userId=64545454&styleId=98080934&includeDisabledStyles=true

Sample Response

 

"recommendedOutfits": [
    {
      "styleId": 456456456,
      "parts": [
        {
          "product": {
            "clickUrl": "https://xxx.com/yyserver/apiclick?a=dbc88fd3561a8ee1&cak=bece98fc549252f3&channelId=bece98fc549252f3&ct=https%3A%2F%2Fwww.xxx.com%2Fshop%2Fus%2Fp%2Foff-the-shoulder-poplin-set-top-54225333%3Fseq%3D04&vg=11d7e6e7-bd72-41d4-c985-656401c27a2e&stid=-1&pti=0&pa=-1&pos=1&p=MIC_140-3299-1512-100&style=1688678540&srcstr=composite_outfit&outfit=250317941078%7C309480036792%7C315780263701%7C315780266360",
            "salePriceCents": 2499,
            "clickTrackingUrl": "https://xxx.com/yyserver/apiclick?a=dbc88fd3561a8ee1&cak=bece98fc549252f3&channelId=bece98fc549252f3&vg=11d7e6e7-bd72-41d4-c985-656401c27a2e&stid=-1&pti=0&pa=-1&pos=1&p=MIC_140-3299-1512-100&style=1688678540&srcstr=composite_outfit&outfit=250317941078%7C309480036792%7C315780263701%7C315780266360",
            "prodUrl": "https://www.xxxx.com/shop/us/p/off-the-shoulder-poplin-set-top-54225333?seq=04",
            "imageUrl": "https://img.xxx.com/is/image/abc/456_456_456_465_prod1",
            "prodName": "Off-The-Shoulder Poplin Set Top",
            "priceCents": 4000,
            "prodId": "456_456_456_465",
            "brand": "abc"
          },
          "partId": 1
        },
        {
          "product": {
            "clickUrl": "https://xxx.com/rrserver/apiclick?a=dbc88fd3561a8ee1&cak=bece98fc549252f3&channelId=bece98fc549252f3&ct=https%3A%2F%2Fwww.xxx.com%2Fshop%2Fus%2Fp%2Fcropped-denim-trucker-jacket-55095828%3Fseq%3D04&vg=11d7e6e7-bd72-41d4-c985-656401c27a2e&stid=-1&pti=0&pa=-1&pos=2&p=456_456_456_465&style=1688678540&srcstr=composite_outfit&outfit=250317941078%7C309480036792%7C315780263701%7C315780266360",
            "salePriceCents": 9000,
            "clickTrackingUrl": "https://xxx.com/yyserver/apiclick?a=dbc88fd3561a8ee1&cak=bece98fc549252f3&channelId=bece98fc549252f3&vg=11d7e6e7-bd72-41d4-c985-656401c27a2e&stid=-1&pti=0&pa=-1&pos=2&p=MIC_144-4083-0112-107&style=1688678540&srcstr=composite_outfit&outfit=250317941078%7C309480036792%7C315780263701%7C315780266360",
            "prodUrl": "https://www.xxx.com/shop/us/p/cropped-denim-trucker-jacket-55095828?seq=04",
            "imageUrl": "https://img.xxx.com/is/image/abc/456_456_456_456_prod1",
            "prodName": "Cropped Denim Trucker Jacket",
            "priceCents": 9000,
            "prodId": "456_456_456_456",
            "brand": "abc"
          },
          "partId": 2
        },
        {
          "product": {
            "clickUrl": "https://xxx.com/yyserver/apiclick?a=dbc88fd3561a8ee1&cak=bece98fc549252f3&channelId=bece98fc549252f3&ct=https%3A%2F%2Fwww.xxx.com%2Fshop%2Fus%2Fp%2Fcurve-love-mid-rise-90s-straight-jean-56240907&vg=11d7e6e7-bd72-41d4-c985-656401c27a2e&stid=-1&pti=0&pa=-1&pos=3&p=456_456_456_456&style=1688678540&srcstr=composite_outfit&outfit=250317941078%7C309480036792%7C315780263701%7C315780266360",
            "salePriceCents": 9000,
            "clickTrackingUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=dbc88fd3561a8ee1&cak=bece98fc549252f3&channelId=bece98fc549252f3&vg=11d7e6e7-bd72-41d4-c985-656401c27a2e&stid=-1&pti=0&pa=-1&pos=3&p=456_456_456_456 175&style=1688678540&srcstr=composite_outfit&outfit=250317941078%7C309480036792%7C315780263701%7C315780266360",
            "prodUrl": "https://www.xxx.com/shop/us/p/curve-love-mid-rise-90s-straight-jean-56240907",
            "imageUrl": "https://img.xxx.com/is/image/abc/456_456_456_456_prod1",
            "prodName": "Curve Love Mid Rise 90s Straight Jean",
            "priceCents": 9000,
            "prodId": "456_456_456_456",
            "brand": "abc"
          },
          "partId": 3
        },
        {
          "product": {
            "clickUrl": "https://xxx.com/yyserver/apiclick?a=dbc88fd3561a8ee1&cak=bece98fc549252f3&channelId=bece98fc549252f3&ct=https%3A%2F%2Fwww.xxx.com%2Fshop%2Fus%2Fp%2Fstraw-platform-heels-53488822%3Fseq%3D02&vg=11d7e6e7-bd72-41d4-c985-656401c27a2e&stid=-1&pti=0&pa=-1&pos=4&p=456_456_456_456&style=1688678540&srcstr=composite_outfit&outfit=250317941078%7C309480036792%7C315780263701%7C315780266360",
            "salePriceCents": 8000,
            "clickTrackingUrl": "https://xxx.com/rrserver/apiclick?a=dbc88fd3561a8ee1&cak=bece98fc549252f3&channelId=bece98fc549252f3&vg=11d7e6e7-bd72-41d4-c985-656401c27a2e&stid=-1&pti=0&pa=-1&pos=4&p=456_456_456_456 800&style=1688678540&srcstr=composite_outfit&outfit=250317941078%7C309480036792%7C315780263701%7C315780266360",
            "prodUrl": "https://www.xxx.com/shop/us/p/straw-platform-heels-53488822?seq=02",
            "imageUrl": "https://img.xxx.com/is/image/abc/456_456_456_456_prod1",
            "prodName": "Straw Platform Heels",
            "priceCents": 8000,
            "prodId": "456_456_456_456",
            "brand": "abc"
          },
          "partId": 4
        }
      ],
      "styleName": "Business Casual"
    },

 

Sample Parameters

Name

Description

recommendedOutfits

All the outfits/ensembles recommended for the given seed product

styloid

The style id is a unique identifier associated with a style created by Merchandiser in Ensemble AI UI.

Parts

Returns that number of parts associated with the ensemble/outfit

clickURL

Click URL for the product

salePriceCents

Sale price of the product

clickTrackingURL

Tracking the product click

prodUrl

URL of the product on client website

ImageUrl

URL of the product Image

prodName

Name of the product

priceCents

Price of the product

productid

External Id of the product

Brand

Brand of the product

partId

Which part this product belong to in the outfit. This is based on the style definition and this will be helpful to design appropriate layout for the outfit.

Tracking Events

When the user clicks on a recommended product from an ensemble, you are required to call a click event tracker for that product before redirecting the user to the product detail page or quick view page. This is to ensure Algonomy can track the click along with the views, so that our products can accurately capture CTR data. This API will expose the following URLs:

  • productURL is the direct URL to the Product Detail Page. Use this URL to link to the product page, likely as the href attribute of an <a> tag.

  • clickTrackingURL tracks a product click without redirecting the user to the Product Detail Page. For SEO purposes, you can use this URL together with productURL and trigger a request to clickTrackingURL via a click event listener.

  • clickURL tracks a product click and redirects the user to the Product Detail Page via an HTTP 301 redirect.

To successfully track clicks, use one of the following options:

  • Use clickURL which automatically tracks a product click and redirects the user to the Product Detail Page, or

  • Use productURL as the final URL, and trigger a request to clickTrackingURL via an event listener. This is the suggested approach when SEO optimization is involved.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
    Review Stage
    Final
  2. Tags
    This page has no tags.