Ensemble AI Client API

Description

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

URL

Production

Use this URL to request ensembles from your production environment.

Copy

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

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.

Copy

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

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
styleId	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:

Copy

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

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

Copy

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

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

Copy

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

Sample Response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
"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 for the given seed product
styleId	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
prodId	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 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.