Introduction
In the SPARQUE backend you manage all the elements needed to provide a great search or recommendations experience, among them the knowledge graph, the algorithms, and the (custom) APIs. SPARQUE users can create their own unique APIs.
This cookbook provides hints how to manage certain use cases when working with SPARQUE APIs.
References
Recipe: Browse Categories
Problem: How to Browse Categories?
Browsing categories consists of two parts: navigating the category tree, and at each branch of the tree displaying the relevant set of products that occur in that branch.
Solution
Navigating the Category Tree
To retrieve the category tree, you can call
...domain.../api/PWA/e/categorytree/results?config=default&count=1000
This call returns pairs of categories as "parent"-"child" combinations. In the simplest implementation, the probability indicates the level of the category tree. Probability 3 means that the parent is at level three, while a root category would be at level one.
"type": [ "OBJ", "OBJ"],"items": [ { "rank": 1, "probability": 3.0, "tuple": [ { "id":"http://schema.org/category/816", "class": [ "http://schema.org/Category" ], "attributes": {"image":["L/9604582-1104.jpg","M/9604582-1104.jpg","S/9604582-1104.jpg"],"name":{"de-DE":"Stromversorgung","en-US":"Power Supplies","fr-FR":"Alimentations"},"online":1,"root":0,"identifier":"816"} }, { "id":"http://schema.org/category/829", "class": [ "http://schema.org/Category" ], "attributes": {"image":["M/3797119-8543.jpg","L/3797119-8543.jpg","S/3797119-8543.jpg"],"name":{"de-DE":"Ladegeräte","en-US":"Battery Chargers","fr-FR":"Chargeurs de batterie"},"online":1,"root":0,"identifier":"829"} } ] },
Retrieve Products
Products can be retrieved via the call
...domain.../api/PWA/e/products/results?config=default&count=30
The result is a set of products with their attributes (for each of the products).
{ "offset": 0, "count": 30, "type": [ "OBJ" ], "items": [ { "rank": 1, "probability": 0.714, "tuple": [ { "id":"http://schema.org/product/6628829", "class": [ "http://schema.org/Product" ], "attributes": {"description":{"en-NZ":"3 Easy steps to beautiful eyelashes & brows. Fabulous no smudge colour that wont wash off. Instead of using mascara daily use 1000 Hour Eyelash & Brow Dye Kit every 4-6 weeks. 12 applications per pack. Dermatologically & ophthalmologically tested. Made in EU."},"image-ref":["product/66/28/829/6628829_00_W350_H456.jpg","product/66/28/829/6628829_00_W110_H143.jpg","product/66/28/829/6628829_00_W1200_H1565.jpg","product/66/28/829/6628829_00_W500_H652.jpg"],"manufacturer-name":"1000HR","name":{"en-NZ":"1000HR Eyelash & Brow Plant Based Kit, Medium Brown"},"short-description":{"en-NZ":"Gentle plant extract brush-in gel to tint brows & lashes. This kit will provide 12 applications, each lasting up to 6 weeks."},"sku":"6628829","supplier-sku":"6628829","price":29.99} } ] },
The parameters p/userid and p/cartId can be used if the ranking of the products should depend on who the user is, or on the items currently being in the cart.
Products can be either masters or variants. Masters are returned as above, each item is a product with its attributes. Below an example is shown of a result with a master and a variant. The item now starts as the top-ranking variant (sku=6448771001). With the variant, the information about the master is also returned, being the part that starts with "mastered-product", referring to "sku": "6448771". With this, you can choose what to display. You can use the image of the variant - this is very useful when e.g. color is a variation - and combine that with the name of the master.
{"rank": 3,"probability": 0.70693069,"tuple": [{"id": "http://schema.org/product/6448771001","class": ["http://schema.org/Product"],"attributes": {"image-ref": ["product/64/48/77/10/01/6448771001_51_W1200_H1565.jpg","product/64/48/77/10/01/6448771001_50_W350_H456.jpg","product/64/48/77/10/01/6448771001_00_W110_H143.jpg","product/64/48/77/10/01/6448771001_51_W350_H456.jpg","product/64/48/77/10/01/6448771001_00_W350_H456.jpg","product/64/48/77/10/01/6448771001_00_W1200_H1565.jpg","product/64/48/77/10/01/6448771001_50_W1200_H1565.jpg","product/64/48/77/10/01/6448771001_50_W500_H652.jpg","product/64/48/77/10/01/6448771001_51_W110_H143.jpg","product/64/48/77/10/01/6448771001_00_W500_H652.jpg","product/64/48/77/10/01/6448771001_51_W500_H652.jpg","product/64/48/77/10/01/6448771001_50_W110_H143.jpg"],"manufacturer-name": "Lyric","name": {"en-NZ": "GOPRO HELMET FRONT MOUNT, black"},"short-description": {"en-NZ": "Mount your GoPro to the front of your helmet in a headlamp-like position."},"sku": "6448771001","supplier-sku": "6448771001","price": 24.99,"mastered-product": [{"description": {"en-NZ": " "},"image-ref": ["product/64/48/771/6448771_50_W110_H143.jpg","product/64/48/771/6448771_00_W110_H143.jpg","product/64/48/771/6448771_50_W350_H456.jpg","product/64/48/771/6448771_00_W350_H456.jpg","product/64/48/771/6448771_00_W1200_H1565.jpg","product/64/48/771/6448771_51_W350_H456.jpg","product/64/48/771/6448771_51_W110_H143.jpg","product/64/48/771/6448771_50_W1200_H1565.jpg","product/64/48/771/6448771_51_W1200_H1565.jpg","product/64/48/771/6448771_00_W500_H652.jpg","product/64/48/771/6448771_51_W500_H652.jpg","product/64/48/771/6448771_50_W500_H652.jpg"],"manufacturer-name": "Gopro","name": {"en-NZ": "GOPRO HELMET FRONT MOUNT"},"short-description": {"en-NZ": "Mount your GoPro to the front of your helmet in a headlamp-like position."},"sku": "6448771","supplier-sku": "6448771","price": 24.99}]}}]},
Filter Total Set of Products by Category
Displaying all products is often not needed. To filter the set of products down to those remaining within a particular branch of the category tree can be done by stacking a call to filter on category:
....domain..../api/PWA/c/locale/en-US/e/products/category:FILTER/p/value/1(816)/results?config=default&count=30
This will return all the products for category "816" and its children.
As value, you can use:
full identifier, e.g. "http://schema.org/category/816"
category identifier, "816"
name of the category, "Power Supply"
Retrieve Facets and Apply Filters
This process is described in Concept - Implementing Search with Sparque.
Recipe: Recommendations
Problem: How Do I Retrieve Which Types of Recommendations?
There are various recommendations that can be applied. SPARQUE users can create custom APIs with custom algorithms.
Solution
Standard Recommendations
The following types of recommendations are available as standard API:
cross sell: ...domain.../api/PWA/e/crosssell/p/userid/1/p/sku/{value}/p/channel/{value}/p/cartid/1(value1)%7C1(value2)/results?config=default&count=30
upsell: ...domain.../api/PWA/e/upsell/p/userid/1/p/sku/{value}/p/channel/{value}/p/cartid/1(value1)%7C1(value2)/results?config=default&count=30
The parameters are:
sku - the identifier of the product on the product detail page. When applied on the cart page, the sku parameter can be omitted, assuming the cartid list can be provided. In that case, the recommendations will be based on the items in the cart.
userid - customer ID as known by the frontend.
channel - in most cases, locale will be sufficient to provide recommendations from the correct product catalog. In some cases, sales organization or channel identifier may be used.
cartid - SKU of products already in the cart. Notation is in tuple format: p/cartId/1(sku1)%7C1(sku2), where 1 is for weight, value is placed between brackets, and multiple values are separated by pipe sign or preferably %7c.
Result
When calling the API, the results returned are product objects, containing attributes and, if applicable, a relation to the mastered-product.
{"offset": 0,"count": 30,"type": ["OBJ"],"items": [{"rank": 1,"probability": 0.714,"tuple": [{"id": "http://schema.org/product/8509285","class": ["http://schema.org/Product"],"attributes": {"image-ref": ["M/8509285-2118.jpg"],"manufacturer-name": "iiyama","name": {"de-DE": "iiyama ProLite X2472HD","en-US": "iiyama ProLite X2472HD"},"short-description": {"de-DE": "ProLite X2472HD - 60.96 cm (24 \") , 1920x1080 Full HD, 3000:1, 250 cd/m²","en-US": "ProLite X2472HD - 60.96 cm (24 \") , 1920x1080 Full HD, 3000:1, 250 cd/m²"},"sku": "8509285","supplier-sku": "8509285","price": 252.25}}]},