Skip to main content

Recommendation API


Particular Audience’s recommendations API is a flexible and robust interface that supports any e-commerce platform or application. The Recommendations API supports all required requests to run real-time personalization of product slots on any website.

Recommendation API

API Base URL

Method: GET
Endpoint: /1.0/ClientRecom

API Response

Each recommendation API has the same response pattern, and this section describes the response object.

Sample Response

NameTypeDescription
typeintResponse type. Any value with negative number means error.
Ex.: 1
codeintResponse code.
Ex.: 0
payloadarray of stringReturn list of product RefId matched in the recommendation method.
Ex.: ["76277"]
messageStringError message in case response type is not successfull.

Personalized Recommendations

Recommended For You Hybrid Recommender

This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.

Tactic Cascade: ‘Viewed With Recently Viewed’ >> ‘Bought With Recently Viewed’ >> ‘Recently Viewed’ >> ‘Popular Items’

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/Personalized?customerId=CUSTOMER_ID'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
CUSTOMER_IDstringQueryCustomer Id. It will be available after the Config API call. You need to store it for subsequent calls.

Response

Response is described here

Personalized PDP

Personalized PDP Recommendations

This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.

Tactic Cascade: Viewed With > Bought With > Visually Similar > Viewed With Recently Viewed > Bought With Cart Contents > Recently Viewed > Popular Items (over 7 days)

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ProductDetail?customerId=CUSTOMER_ID&productRef=PRODUCT_REF&items[0]=PRODUCT_REF&items[1]=PRODUCT_REF&filterOutOfStock=false'
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/Cart?customerId=CUSTOMER_ID&items[0]=PRODUCT_REF&items[1]=PRODUCT_REF&filterOutOfStock=false'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
CUSTOMER_IDstringQueryCustomer Id. It will be available after the Config API call. You need to store it for subsequent calls.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.
itemsarrayQueryThis takes in an array of Ref IDs in the customer cart (used for Bought with Cart Contents)
filterOutOfStockbooleanQueryWhether to filter out of stock items.

Response

Response is described here

Similar Items-Based Hybrids

These are Similar Item-based endpoints that have been configured with fall-throughs in case one tactic does not have a result. The fall-through behavior can be seen in the Tactic Cascade description.

Viewed Together + Similar Attributes Hybrid Recommender

This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.

Tactic Cascade: ‘Collaborative Filtering Jaccard Items Viewed Together’ >> ‘Similar Attributes’ >> ‘Popular Items’

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ViewedTogetherAttributes?productRef=PRODUCT_REF'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.

Response

Response is described here

Viewed Together + Visually Similar Hybrid Recommender

This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.

Tactic Cascade: ‘Collaborative Filtering Jaccard Items Viewed Together’ >> ‘Visually Similar’ >> ‘Popular Items’

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ViewedTogetherVisuallySimilar?productRef=PRODUCT_REF&productStyleId=STYLE_ID'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.
STYLE_IDstringQueryProductStyleId being viewed. Required if the website is configured to use StyleId for VSR

Response

Response is described here

Similar Attributes + Viewed Together Hybrid Recommender

This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.

Tactic Cascade: ‘Similar Attributes’ >> ‘Collaborative Filtering Jaccard Items Viewed Together’ >> ‘Popular Items’

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/SimilarAttributesViewedTogether?productRef=PRODUCT_REF'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.

Response

Response is described here

Visually Similar + Viewed Together Hybrid Recommender

This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.

Tactic Cascade: ‘Visually Similar’ >> ‘Collaborative Filtering Jaccard Items Viewed Together’ >> ‘Popular Items’

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/VisuallySimilarViewedTogether?productRef=PRODUCT_REF&productStyleId=STYLE_ID'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.
STYLE_IDstringQueryProductStyleId being viewed. Required if the website is configured to use StyleId for VSR

Response

Response is described here

Used to return trending products (by purchases) across the website. This tactic is based on all customers’ purchase behavior.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/PopularItems'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.

Response

Response is described here

Collaborative Filtering

Collaborative Filtering Jaccard Items Viewed Together

Used to return the list of items that are often viewed with a product. This tactic is based on all customers’ viewing behavior.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ViewedTogether?productRef=PRODUCT_REF'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.

Response

Response is described here

Collaborative Filtering Jaccard Items Bought Together

Used to return the list of items that are often bought with a product. This tactic is based on all customers’ purchase behavior.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/BoughtTogether?productRef=PRODUCT_REF'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.

Response

Response is described here

Visually Similar

Used to return the list of items that have similar images to a product. This tactic is based on the image compare program.

Visually Similar Request (by product identifier)

This endpoint will return a list of similar-looking products when given a product identifier.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/OnlyVisuallySimilar?productRef=PRODUCT_REF'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.

Response

Response is described here

Visually Similar Request (by style identifier)

This endpoint will return a list of similar-looking products when given a style identifier.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/OnlyVisuallySimilar?productStyleId=STYLE_ID'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
STYLE_IDstringQueryThis is the style identifier. The style identifier is an ID that sits below the product ID but is not as granular as a variant level identifier/SKU.

Response

Response is described here

Similar Attributes

Used to return the list of items that have similar attributes to a product. This tactic is based on the attributes compare program.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/OnlySimilarAttributes?productRef=PRODUCT_REF'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
PRODUCT_REFstringQueryProduct Ref Id. It should be same what we use in Update Product call.

Response

Response is described here

Items Often Bought Together

Items Often Bought Together - Cart Page

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/BoughtTogetherCartContent?items[0]=PRODUCT_REF&items[1]=PRODUCT_REF'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
itemsarrayQueryThis takes in an array of Ref IDs that you want to query for

Response

Response is described here

Items Often Bought Together - Recently Viewed Items

Used to return the list of items that are bought together with the recently viewed items of the current customer. This tactic is based on all customers’ purchase behavior.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/BoughtTogetherRecentlyViewed?customerId=CUSTOMER_ID'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
CUSTOMER_IDstringQueryThis the customer ID you want to query for.

Response

Response is described here

Items Often Viewed Together - Recently Viewed Items

Used to return the list of items that are viewed together with the recently viewed items of the current customer. This tactic is based on all customers’ view behavior.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ViewedTogetherRecentlyViewed?customerId=CUSTOMER_ID'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
CUSTOMER_IDstringQueryThis the customer ID you want to query for.

Response

Response is described here

Recently Viewed

Used to return the list of items that are viewed in the most recent session. This tactic is based on the current customer’s tracked data.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/RecentlyViewed?customerId=CUSTOMER_ID'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
CUSTOMER_IDstringQueryThis the customer ID you want to query for.

Response

Response is described here

Historic Viewed Items

Used to return the list of items (maximum 20 items) that are viewed in the previous sessions of the current customer. This tactic is based on that customer’s tracked data.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/HistoricViewed?customerId=WEBSITE_ID'
NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.
CUSTOMER_IDstringQueryThis the customer ID you want to query for.

Response

Response is described here

Bundles: Items Often Bought Together

Used to return sets or a list of items that are bought together with the provided list of item(s) on either a product page or cart page.

Request CURL & Params

curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/bundle'

Header Params

NameTypeParam TypeDescription
WEBSITE_IDstringHeaderWebsite ID. Available in web app or PA will provide.

Body Params

NameTypeParam TypeDescription
product_ref_idsarrayBodyProduct Ref Id. It should be same what we use in Update Product call.
setCountintBodyNumber of bundles/sets to be returned (Default is 1).
countintBodyNumber of items in each bundle/set (Default is 1 + # of product_ref_ids).
filter_out_of_stockbooleanBodyFilter out of stock items.

Response

NameTypeDescription
typeintResponse type. Any value with negative number means error.
Ex.: 1
codeintResponse code.
Ex.: 0
payload2D array of stringReturn list of product RefId matched in the recommendation method.
Ex.: [["1234", "5678"], ["1234", "8972"]]