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. 

To get results to the front end (or any other customer facing application), it can call the relevant API to get the results. The list of available endpoint sets and endpoints can be accessed in the backend. Documentation accompanying the endpoint set is also accessible via this page. SPARQUE users can create their own unique APIs. This concept focuses on the use of preconfigured default APIs. 

This concept describes how to use and combine specific endpoints to create various search functions, from search results and filters to search suggestions. 

References

• Guide - Use SPARQUE with Postman

• Cookbook - Search, Categories and Recommendation APIs

Getting Started

Calls Explained

The SPARQUE endpoints consist of a number of elements.

For example, this call will give you a set of search results in which the content varies with the parameter values applied:

https://rest.sparque.ai/4/testintershop/api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1%281%29&7c1%282%29/results?config=default&count=30

*1: SPARQUE makes use of context parameters. It is recommended to place it at the start of the call, before a specific endpoint is called. See section Parameters.

Preconfigured APIs

With SPARQUE you build your own strategies and connect them to the endpoint in the API. Your SPARQUE environment has also a set of multiple preconfigured APIs which, if needed, can be modified.

Preconfigured Stacked APIs

Stacking means the results of one call can be immediately used as the input for a next call. To retrieve relevant facets, for example, you need to know which products are returned in the result set. Stacking looks like the following, where two endpoints with their respective parameters are placed sequentially:

.....api/X/e/search/p/keyword/ABCD..../e/facets/..... 

Stacking calls this way, the second part /e/facets... will use the results from the preceding endpoint /e/search/....

Parameters

The parameters are used to define values which are used within the strategies. An endpoint can have 0 to many parameters. Filling multiple parameters using the query API is done by appending them. SPARQUE makes use of context parameters. Context parameters hold for all further query endpoints in the URL. They can be specified at any location in the URL (even before the first query endpoint).

Because of the possibility that a locale parameter is needed in various parts of the call, it is recommended to place it at the start of the call, before a specific endpoint is called. That way, it will operate as a context parameter and be valid for various parts of the call rather than having to place it as a local parameter - behind a specific endpoint - multiple times. 

Response Type

Request Options

Product Objects 

For most of the use cases, the result set that is returned contains product objects. 

Products can be either masters or variants; each item is a product with its attributes. Masters are returned without reference to a mastered-product. When a result is a variant, it will be returned with reference to the master, see example below.

The item is the top-ranking variant (sku=6448771001). With the variant, the information about the master is also returned. It is 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,
"tuple":[
   {
      "id":"http://schema.org/product/6448771001",
      "attributes":{
         "image-ref":[
            "product/64/48/77/10/01/6448771001_51_W1200_H1565.jpg"
         ],
         "manufacturer-name":"Gopro",
         "name":{
            "en-NZ":"GOPRO HELMET FRONT MOUNT, Black"
         },
         "sku":"6448771001",
         "mastered-product":[
            {
               "description":{
                  "en-NZ":" "
               },
               "image-ref":[
                  "product/64/48/771/6448771_50_W110_H143.jpg"
               ],
               "manufacturer-name":"Gopro",
               "name":{
                  "en-NZ":"GOPRO HELMET FRONT MOUNT"
               },
               "sku":"6448771"

Search Implementation

Most websites make usage of a search bar and a result page. We will show which APIs are normally used for this and how they are implemented. We created screenshots with a wireframe. Within this wireframe we marked positions. We will explain which API is behind the mark and explain it with an example.

To make it more readable we define {{url}} as the elements {domain}{/version}/{workspace}/{api}.

For example: https://rest.sparque.ai/4/testintershop/api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1%281%29&7c1%282%29/results?config=default&count=30

• Domain = https://rest.sparque.ai/

• Version = 4

• Workspace = testintershop

• API = PWA

This will be: {{url}}/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1%281%29&7c1%282%29/results?config=default&count=30

Search Bar

Most search bars are used with 3 types of suggestions.

• Keyword suggestions

• Product suggestions

• Category suggestions

Wireframe:

When a user enters a keyword, this word is used as a parameter for keyword suggest, product suggest, and category suggest.

Keyword Suggest

These suggestions come from the API endpoint keywordsuggest.

Example:

• {{url}}/e/keywordsuggest/p/keyword/laptop/results

Explanation:

The user enters the keyword “laptop”. We will get all relevant keyword suggestions related to that search term.

Product Suggest

These suggestions come from the API endpoint productsuggest.

Example:

• {{url}}/e/productsuggest/p/keyword/laptop/results

Explanation:

The user enters the keyword “laptop”. We will get all relevant products related to that search term.

Category Suggest

These suggestions come from the API endpoint categorysuggest.

Example:

• {{url}}/e/categorysuggest/p/keyword/laptop/results

Explanation:

The user enters the keyword “laptop”. We will get all relevant categories related to that search term.

Result Page

To show the result page, we need the API search.

Example:

• {{url}}/c/locale/nl-NL/e/search/p/userId/none/p/stock/true/p/promotion/none/p/pinned/none/p/keyword/laptop/p/cartId/1(none)/results,count

Explanation:

We asked the API to provide the results for locale nl-NL, to show only products with stock and related to the keyword “laptop”. We do not have any data of userId, promotion, pinned and cartId parameters, so we filled in “none”.
The output will be products as objects (marked in orange border in the screenshot below).

Pagination

By default, the results are limited to 10. To show more or less products, you can expand your request with the request options.

For example: (refer to the image above with 8 products on the first page)

• {{url}}/c/locale/nl-NL/e/search/p/userId/none/p/stock/true/p/promotion/none/p/pinned/none/p/keyword/laptop/p/cartId/1(none)/results,count?count=8&offset=8

Explanation:

• count will give the number of results (8)

• offset will start the results from a rank (8), so the first 8 are skipped
  (Thus, it shows the second page of results.)

Sorting Options

With SPARQUE we have a default sorting on relevance. It is based on your own strategy. Sometimes you want to sort the results. In the standard set you can sort the results based on the product name (ascending and descending).

By default, you can request the defined sorting options.

Example:

• {{url}}/e/sortings/p/locale/nl-NL/results

Explanation:

This will give you the possible sorting options. For example, with identifier “namedown”.

This value can be used to sort through a stacked API endpoint.

Example:

• {{url}}/c/locale/nl-NL/e/search/p/userId/none/p/stock/true/p/promotion/none/p/pinned/none/p/keyword/laptop/p/cartId/1(none)/e/namedown/p/locale/nl-NL/results,count

Explanation:

This will sort the results from search on keyword “laptop” by the productname - descending.

Number of Search Results

Mostly the result page displays how many results are found related to a keyword.

To define the number of results, you have to add request options to the API.

Example:

• {{url}}/c/locale/nl-NL/e/search/p/userId/none/p/stock/true/p/promotion/none/p/pinned/none/p/keyword/laptop/p/cartId/1(none)/e/namedown/p/locale/nl-NL/results,count

Explanation:

When we add a count after the results, the API will give information about the number of results. This will be at the end of the results and looks like this:

Show Filters

With SPARQUE it is possible to apply filters to the result set. Basically, there are two types of filters:

• Predefined filters are best used for product attributes and relations that are (nearly) always present, such as brand and category. These filters will always be on display at a fixed position.

• Dynamic filters are best used for product attributes and relations which are depending on the result set, such as color or hard disk storage. You only want to display them when they are relevant to display.

Predefined Filters

The advantage of defined facets is that each facet has its own definition. As a result, the score and the count may differ. For example, categories may be ranked in alphabetical order while brands are ranked by the number of products. For each predefined filter you will need to have a dedicated API endpoint.

Defined facets use predefined endpoints. Having a predefined endpoint implies that an endpoint can have its own strategy assigned to it. This way, the behavior of one defined facet can differ from the next one. To be able to use brand as a defined facet, there must be a corresponding endpoint called brand in the endpoint set that is called.

To know which defined facets are present in the workspace, you can call: /e/fixedFacets/... 

As default, there are two defined facets:

• category

• brand

Example:

• {{url}}/e/fixedFacets/results

Explanation:

This will give all the predefined filters.

Get All Values of Predefined Filters

To get all values of a specified predefined filter, proceed as follows.

Example:

• {{url}}/e/search/p/userId/none/p/stock/true/p/promotion/none/p/pinned/none/p/keyword/laptop/p/cartId/1(none)/e/category/p/locale/nl-NL/results,count

Explanation:

We added the stacked endpoint named “category”. Within this strategy we defined to determine the related categories based on the result set of “search”. The result set of the stacked endpoint “category” will be the relevant categories which can be used as a filter. See image below.

To get the brand options, stack ..../e/brand/... directly behind the call for search ....e/search/....., e.g.:

domain.../api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/printer/p/cartId/1(1)/e/brand/results?config=default&count=30

The part e/search/p/userId/1/p/keyword/printer/p/cartId/1(1) is the search call and /e/brand the stacked API to retrieve the options for brand. 

Alternatively, call: 

...domain..../api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1(1)/options/brand?config=default&count=30 

replacing ....e/brand/results with .../options/brand.

Note that the notations of the results are different between the two calls. The latter notation, /options/XYZ/... is preferred as it allows you to call multiple fixed facets in one group: 

...domain..../api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1(1)/optiongroup/category%7cbrand?config=default&count=30

The facets are separated by pipe sign or preferably %7c.

Filter on a Value of a Predefined Filters

To filter on one or more values of the facet brand, a filter is applied by stacking a call on top of the first call that provided the original result set:

...domain..../api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1(1)/e/brand:FILTER/p/value/1(Freecom)%7c1(Lenco)/results?config=default&count=30.

where the part ....e/brand:FILTER/p/value/1(value1)%c1(value2).... is stacked to the preceding call for results ..e/search/p/....

• e/brand:FILTER/ calls the brand filter

• p/value determines which values the result set should be filtered on. Multiple values can be added by using the tuple notation "weight, openbracket, value, closebracket". Multiple values are separated by pipe sign or preferably %7c, e.g.,
  p/value/1.0(Freedom)%7c1.0(Lenco)

To apply multiple filters, e.g., also a category filter, simply append:

...e/category:FILTER and appropriate values 

....domain.../api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1(1)/e/brand:FILTER/p/value/1(Freecom)%7c1(Lenco)/e/category:FILTER/p/value/1(Laptop)/results?config=default&count=30

After the values have been selected to apply as filter, the new result set can be queried for facets and options:

....domain.../api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1(1)/e/brand:FILTER/p/value/1(Freecom)%7c1(Lenco)/options/brand?config=default&count=30

Apply Multiselect on a Predefined Filter

When a user selects a filter the result set is, of course, based on your selection. This gives us a little problem on user experience. For example, you will filter on a certain category. Based on the selected filter the new result set has been requested to the API. Unless products are assigned to multiple categories, the products within the result set are not assigned to other categories anymore. The user now has no possiblity to click on other categories or to return to the previous results.

Adding the option multiselect=true will return the available options ignoring the last applied filter so that the options are not limited to the values that are present in the new result set. The feature multiselect=true is only available for defined facets. 

....domain..../api/PWA/e/search/p/userId/1/p/keyword/printer/p/cartId/1(1)/e/brand:FILTER/p/value/1(Canon)%7c1(Brother)/options/brand?config=default&count=30&multiselect=true

Dynamic Filters

Each product has many product properties. Some of these are not relevant enough to be displayed. SPARQUE is able to calculate which filter is relevant to be displayed. For example, if 80% of the products in a result set have the property 'diameter', it is probably relevant. If only 10% of the products have the 'diameter' property, it is probably not relevant. SPARQUE calculates on the fly which facets are relevant to the result set (so-called dynamic facets). Dynamic facets have the advantage that they can be called using a generic call. Unlike defined facets, a dynamic facet does not need to be defined as an endpoint in the backend.

To get all dynamic filters with the values, you can stack the endpoint strings_facets_options.

Example:

• {{url}}/c/locale/nl-NL/e/search/p/userId/none/p/stock/true/p/promotion/none/p/pinned/none/p/keyword/laptop/p/cartId/1(none)/e/strings_facets_options/p/locale/nl-NL/results

Explanation:

This request will give you all property names with property values.

The output will be something like:

{
   "offset":0,
   "count":30,
   "type":[
      "STRING",
      "STRING"
   ],
   "items":[
      {
         "rank":1,
         "probability":347.0,
         "tuple":[
            "Colour_of_product",
            "Black"
         ]
      },
      {
         "rank":2,
         "probability":135.0,
         "tuple":[
            "USB 2.0 ports quantity",
            "1"
         ]
      },
      {
         "rank":3,
         "probability":128.0,
         "tuple":[
            "Plug and Play",
            "Y"
         ]
      },
      {
         "rank":4,
         "probability":116.0,
         "tuple":[
            "Internal",
            "N"
         ]
      },
      

The probability indicates the amount of products associated with the facet value. There are 347 products with 'Colour_of_product' = 'Black'.

Filter by Value

After the call for the results and, if applicable, any filters already applied, you can stack a filter by appending 

...q/facet_filter/p/attribute/value1…valueX, with values in tuple notation to 

...domain.../api/PWA/c/locale/en-US/e/search/p/userId/1/p/keyword/dvd/p/cartId/1(1)/e/facet_filter/p/attribute/Weight/p/value/1(1100%20g)%7c1(350%20g)/results?config=default&count=30

This will result in a product set with products having "weight" = "1100g" or "weight" = 350g.

To continue filtering on other attributes and values, simply keep appending filters: 

...domain.../api/PWA/c/locale/en-US/e/items/p/userid/1/p/cartId/1(1)/e/facet_filter/p/attribute/Weight/p/value/1(1100%20g)%7c1(350%20g)/e/facet_filter/p/attribute/Colour_of_product/p/value/1(Black)/results?config=default&count=30

Apply Multiselect

Dynamic facets face the issue that once a filter has been applied, there is no way of knowing what preceded the filter. To make use of multiselect, you need to apply a workaround as the feature multiselect=true is only available for defined facets. There is no equivalent for dynamic facets. 

If the original call including filters is:

....domain..../api/PWA/c/locale/en-US/e/items/p/userid/1/p/cartId/1(1)/e/facet_filter/p/attribute/Weight/p/value/1(1100%20g)%7c1(350%20g)/e/facet_filter/p/attribute/Colour_of_product/p/value/1(Black)/results?config=default&count=30

this will result in a product set with products having "weight" = "1100g" or "weight" = 350g.

You can call the facets and options after having received the filter results by appending .....e/strings_facets_options/... as follows:

...domain..../api/PWA/c/locale/en-US/e/items/p/userid/1/p/cartId/1%281%29/e/facet_filter/p/attribute/USB%202.0%20ports%20quantity/p/value/1(%223%22)/e/facet_filter/p/attribute/Colour_of_product/p/value/1%28Black%29/e/strings_facets_options/results?config=default&count=1000 

However, calling the strings_facets_options at this point will obviously only return the values represented in the set, i.e. AFTER the filter for "Colour_of_product" = "Black" has been applied. In other words, no other options than "Black" can appear. What is to be done? When two filters have been applied in sequence, you want to reserve the multiple options of the last facet PRIOR to applying the last filter. 

Therefore, for multiselect, all facets and options may be called, EXCEPT THE ATTRIBUTE LAST APPLIED AS FILTER:

...domain..../api/PWA/c/locale/en-US/e/items/p/userid/1/p/cartId/1%281%29/e/facet_filter/p/attribute/USB%202.0%20ports%20quantity/p/value/1(%223%22)/e/facet_filter/p/attribute/Colour_of_product/p/value/1%28Black%29/e/strings_facets_options/p/except/Colour_of_product/results?config=default&count=1000 

This call contains an 'except' parameter to exclude any options from the most recently applied facet.