Recommendations

Constructor.io recommendations bring the same personalization graphs, conversion optimization and product data used to power browse and search to product recommendations.

Rather than offer fixed endpoints such as "Recently-viewed items" or "Complementary Items", Constructor.io implements recommendations using two related concepts: pods and strategies.

Pods represent a specific location on a page or set of pages (template) where recommendations may be rendered. A page may have one or more pods. You may have several pods on the homepage, a pod on the product detail page or in an email campaign.

Strategies represent a particular algorithm used to generate recommendations. Currently, a pod can be assigned a (single) strategy, but the capability is possible in the future to support multiple strategies in a single pod. Example strategies might be "Recently viewed," "Alternative items," etc.

Available strategies#

Constructor.io provides several strategies that can be associated with a given pod. Currently the association is configured @ onboarding and upon request thereafter.

Recently Viewed Items#

The simplest but often most-interacted-with strategy: Show a user’s most recently viewed items.

User Featured Items#

Provide personalized recommendations to a user based on their entire search, view, click, add to cart and purchase history. This algorithm is particularly valuable on homepages and zero result pages -- anywhere outside the context of a particular product page.

Alternative Items#

Show items a user might consider as an alternative to a particular item or set of items. For example, if a user is looking at toothpaste, this algorithm would most likely show other sizes or brands of toothpaste.

Complementary Items#

Show items a user would purchase in addition to a particular item or set of items. For example, if a user is looking at toothpaste, this algorithm would tend to show toothbrushes and dental floss.

Zero-result Suggested Items#

Show items to users on a zero-result page based on the term and data on intent Constructor has collected. The strategy primarily leverages refinements data -- what other users have clicked, added to cart and/or purchased after encountering this zero-result page. Useful to quickly capture lost conversions on zero result pages. Will return zero or more items depending on behavior and available data.

Filtered items (Show more from given facet)#

Show items from a provided filter expression, such as grade: 6th, or recommended use: fishing, and optionally focus these on items more similar to a given product. If you sell educational books to an audience of teachers, you could apply this strategy on product pages to show products most similar to the current product within a specific grade level.

The only requirement for this strategy is a filter expression of the format filters[filter_name]=filter_value, as you would provide in browse or search endpoints. You may include several facets, such as filters[grade]=6&filters[Size]=S. Providing the optional item_id will prioritize items more similar to a particular product, which product will not be returned as a recommendation (to avoid duplication).

Create pod#

There is not yet a customer-facing API for pod creation and configuration. To define the pods for your app or web property, reach out to support@constructor.io or in your dedicated Slack channel.

Retrieve recomendations#

HTTP Request#

GET https://ac.cnstrc.com/recommendations/v1/pods/[pod_id]?key=[your key]&section=[section]&item_id=[item id]&num_results=[num results]

URL Parameters#

ParameterDescription
pod_idPod identifier

Query Parameters#

ParameterRequired?Description
keyYesThe index from which you'd like to retrieve recommendations.
sectionYesThe index section you'd like to retrieve recommendations from, this is typically Products.
num_resultsNoThe number of recommendations to return. Defaults to 10. Generally you should request only the recommendations you intend to display to simplify tracking.
item_idYes, if strategy is alternative or complementaryItem id for which to retrieve recommendations. You can pass multiple item ids, e.g. &item_id=id1&item_id=id2, which may be useful, for example, for cart page recommendations.
uiYes, if strategy is user featured or recently viewed itemsUser id to retrieve recommendations for.
filtersYes, if strategy is filtered itemsA filtering expression with which to retrieve results.