Cookbook - Search, Categories and Recommendation APIs


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.


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. 


Navigating the Category Tree 

To retrieve the category tree, you can call 


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":"",                "class": [                    ""                ],                "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":"",                "class": [                    ""                ],                "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


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":"",                    "class": [                        ""                    ],                    "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": "","class": [""],"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: 


This will return all the products for category "816" and its children.

As value, you can use:

  • full identifier, e.g. ""

  • 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. 


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. 


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": "","class": [""],"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}}]},

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to if you experience login issues,
or if you want to register as customer.