General concept

Objectives

Sensefuel is a search and product discovery platform that leverages the full power of next-generation AI, engineered exclusively for ecommerce.
Sensefuel provides several API endpoints to retrieve the information needed to build your experiences and displays.
These displays can be of multiple types: search, suggestions, landing page, navigation page (PLP), product page (PDP), product selections, etc.

Operation

This API can be reached in HTTP(s) on the entry point api.sensefuel.live.
APIs are called with application authentication keys and entry point dedicated to Sensefuel API activity requests (as described in the Sensefuel backend: Sensefuel > Apis > Settings ).
This API must be called from your servers and not from your sites / applications directly.

Calls are made via GET/POST methods.
When required, query bodies are sent as JSON documents.
Responses are always sent back as JSON documents.
The HTTP response code makes it possible to follow the correct interpretation of the requests.

General purpose

Instant response

The Discovery API aims to provide hyper-personalized results for every user action, in very low response times.

Behavioral analysis

To enable Sensefuel platform to learn from your customers behavior, the use of the Discovery API should be coupled with the use of our Activity Tracking API.
This API ensures:

the individualization of results;

the creation of Key Performance Indicators available in for business users in the platform;

the AI to learn from captured behaviors, enabling Sensefuel to become an even more efficient seller.

If the Discovery API is used on your website, the tracking can eventually be substituted by Sensefuel JavaScript tag.

Individualized response

One of the key strengths of Sensefuel platform is its ability to deliver hyper-personalized results for each user.

Two prerequisites to deliver this feature:

the use of Activity Tracking API (or the implementation of Sensefuel JavaScript tag on your site),

the use of a user identifier (user_id) generated by the Activity Tracking API or the JavaScript tag during calls made to the API.

The properties of this identifier as well as the methods of recovery and exchange are described in the section Tracking module.

Important note
The results provided by Sensefuel technology are individualized, the use of any caching system of these results is naturally to be avoided.

Retrieving the User ID and the Session ID via the JavaScript tag

Sensefuel JavaScript tag enables you to integrate a plug-and-play product search and personalized recommendation solution into your e-commerce website. Additionally, it is also possible to manage the user tracking with the JavaScript tag to feed our AI with user behaviors and provide actionable analytical data.

In some situations, you may want to use our APIs to implement search features, manage product listing pages, or handle recommendations while still benefiting from the user tracking handled by our tag. Below, we explain how to retrieve the user_id generated by our tag and use it with our APIs.

Tracking features of the Sensefuel JavaScript tag

The Sensefuel tracking tag provides several key features:

Compliance with GDPR regulations

Assignment of a unique user ID

Assignment of a session ID

Tracking of the purchase journey (searches, product listings views, product detail views, add-to-cart actions, cart validation, etc.)

Retrieving the User ID

Accessing the Sensefuel JavaScript Interface

The user ID is accessible through a JavaScript interface exposed by the Sensefuel tag. This interface is available under the global variable window.sensefuel_a038457e.

To retrieve the user ID, use the following call:

Retrieving the Session ID

Just like the user ID, the session ID is accessible via the JavaScript interface exposed by the Sensefuel tag.
The following call will allow you to retrieve it:

Precaution

Before accessing this interface, ensure that the tag is fully loaded on the page. If you attempt to call it before the tag is available, the retrieval of one of those IDs (user or session) will fail.

Using the User and Session IDs with Sensefuel APIs

We distinguish two cases for using the Sensefuel APIs:

Dynamic Client-side Calls (Client-side Rendering)

In this case, the API is dynamically called at runtime from the browser (either directly or via an intermediary server you control).

Wait for the window.sensefuel_a038457e interface to become available.

Retrieve the user ID:

Or retrieve the session ID:

Pass these identifiers along to our Discovery or Recommend APIs.

Server-side Calls (Server-side Rendering)

For SEO and performance reasons, you may choose to call our APIs from the server to pre-render personalized content.

On the user's first page visit, no ID will be available. The page can be generated without an ID.

Once the page is loaded, the Sensefuel tag automatically generates both types of identifiers.

To pass this user ID to the server during subsequent visits, store it in a first-party cookie:

Similarly, you can transmit the session ID by storing it in a first-party cookie:

You can transmit both IDs through the first-party cookie:

The server can then retrieve this cookie on every request or page load and use the IDs it contains to call our APIs.

The first-party cookie setup code provided is indicative, and you may adjust the path, SameSite, Expires, Domain, and other cookie options to comply with your cookie management policy (MDN Documentation).

User ID Updates

The Sensefuel tag may regenerate a new user ID in certain scenarios, such as when users refuse cookies under GDPR policies. In such cases:

A new user ID will be generated for every session.

Make sure to update the first-party cookie on each page load.

Available actions

The Discovery API describes multiple actions which describe what you will do about the results:

search

navigation

landing_page

product_selection

product_sheet

suggested_keywords

zero_results

Our APIs will adapt the results according to the action and its e-commerce context usage, especially the ranking of the results.

Moreover, the settings action provides you access to information related to the settings of certain features that business users have configured : user sorting, spotlights, labels, etc.

Each action is combined with :

one or more base queries describing the data to retrieve

a call context to choose the suitable suggest algorithm

a set of modules describing the information to retrieve in the results

user actions corresponding to their interactions with the results displayed

All the associations are described in the section actions.

Base queries

To facilitate data recovery, the Discovery API provides a set of base queries:

terms: search terms associated with articles/contents

search_scope: scopes in which articles are ventilated

search_attributes: article characteristic

search_product: article IDs or references

context and flavor: for suggestion, call context and usage description

These base queries are completed with these parameters:

segments: User segment to scope the search

These base queries are completed with these parameters:

mandatory track_id : session identifier, generated at each new web session or opening of the application

mandatory user_id : unique user identifier, valid between multiple sessions. Otherwise (refusal of consent for example), you can send the value of the track_id.

optional store_id : apply search to a specific seller/dealer/store.

According to your needs and actions, you can choose the most appropriate query.

Calls modularization

In order to facilitate its integration, the API is designed to provide a set of elements related to the query made:

items: recovery of articles that match the query

facets: recovery of filters and filter values related to the articles

scope_pages: proposal of scopes associated with articles

univers_pages: proposal of universes associated with articles

spotlights: spotlights associated with articles

acp: completion suggestions of the search term

references: recovery of articles that match the query by their reference(s)

shortcuts: recovery of redirects that match the query

contents_kicker: content types suggestions (❕ only for Sensefuel MAX)

contents_items: recovery of contents that match the query (❕ only for Sensefuel MAX)

contents_facets: recovery of filters and filter values related to the contents (❕ only for Sensefuel MAX)

suggestions: recovery of suggestions of searches, articles, scopes, spotlights

suggested_keywords, suggested_scope_pages, suggested_spotlights and suggested_shortcuts: get search, scopes, spotlights and shortcuts suggestions

showcases: get showcases related to request

To complete these results, some modules have an utility purpose:

spell_check: recovery of the corrected term which was automatically used for the search

bag: returns information sent in the API call

statistics: returns information related to the query execution

The tracking module is dedicated to the personalization of calls.
Finally, the settings module is systematically sent in the results in order to indicate if parameters which are required to correctly interpret the results have changed.

You can decide, according to your needs, to choose the desired elements and associated informations.

`user_actions`

The user actions are used to interpret typical interaction performed on a result:

apply_filters: apply a filter

apply_scopes: select a scope

apply_spotlights: use a spotlight

apply_content_type: filter the content search on a specific content type (❕ only for Sensefuel MAX)

apply_content_filters: apply a filter on contents (❕ only for Sensefuel MAX)

These query modifiers are optional.

Effects on results

User actions will influence the results of the associated modules, according to the following correspondence table, in order to match the expectations of navigation on a set of products:

User action	Module
`apply_filters`	`facets`
`apply_scopes`	`scope_pages`
`apply_spotlights`	`spotlights`
`apply_content_filters`	`contents_facets`

Example

A user searches for jean.
We send the following query:

search on jean (terms query)

articles recovery (items module);

recovery of available colors (facets module).
The result will contain a list of jeans and the associated colors, for example red, black and blue.

Then, this user will select the red color.
We therefore send the following query:

search on jean (terms query, items module);

with the red color applied (apply_filters user action);

articles recovery (items module);

recovery of available colors (facets module).
The result will then contain red jeans.
Also, the color facet will contain all other colors available on jean (black and blue) in addition to the selected red.
So this user can select other colors to reopen the result.

The availability of user actions are explained in the dedicated section user_actions.

Access

In order to guarantee the confidentiality and the integrity of the exchanges, calls to the API are made via the https protocol.

URL example:
https://api.sensefuel.live/discovery/96cd2378-exemple-1-b92af0700c54/{action}

Add the x-api-key header to authenticate yourself.

curl --location 'https://api.sensefuel.live/discovery/96cd2378-exemple-1-b92af0700c54/{action}' \
--header 'Content-Type: application/json' \
--header 'x-api-key: 7bd7282e-exemple-2-b0aeb0a59382' \
--data '{
    ...
}'

The URL to access your API is available in the menu APIS > Settings.

This URL contains, among other things, your key. This key can be regenerated if you suspect, for example, a misuse of your API.

It's possible to limit the maximum number of calls per minute that the API will respond. This is to avoid, in case of error or fraudulent use, unnecessarily overloading your environment.

The last member of the URL is the action you want to execute.

Call format

Calls are made exclusively in POST method.

The call body consists of a JSON document. Therefore, among the headers call, you need to provide the Content-type: 'application/json'.

Response format

The results returned by the API are provided in the response body as JSON document.

In addition to this documentation, in response bodies, we reserve the right to add new properties and modules as we add new features to our product.

Many modules return an attribute named pr for present relevance. Based on our AI algorithms, value 0 means that you should display the associated data, else 1.

The status code HTTP returned in response allows you to identify the correct execution of the processes or the error encountered if any.

Errors management

It is possible for various reasons that the API call generates an error.

If an error is encountered, the response is always returned as a JSON document, with theerror member as root.

Example for a call with an empty search term:

In case of error, the response is transmitted with the appropriate HTTP status code (in our example: 400 = Bad Request).

Exchange structure

HTTP request

POST https://api.sensefuel.live/discovery/{site-uuid}/{action}

URL parameters

Name	Description
`site-uuid`	String -- Site ID
`action`	String -- played action

Request body

The call body is composed of 3 "root" members:

Nom	Description
`query`	Contains base queries and querie modifiers
`user_actions`	Apply user actions on a result
`modules`	Contains the modules carrying the desired elements and the associated information in the response

Example:

Response body

If the request is successful, the response body is composed only of the member modules containing the modules specified during the call (items in this example) and the corresponding results.

Query

Query is an object that contains base queries and query modifiers.

Base queries are:

terms: searches for the given terms

search_scope: searches in a given categories

search_attributes: searches in the characteristics of an article

search_product: searches articles by identifiers

If the action allows the use of several base queries, then the result is a logical AND between each of these base queries.

Base query: `terms`

This query requires a non-empty expression member corresponding to the expression entered by the user.

Example :

By default, the API embeds a function of automatic correction of the searched terms (SpellChecker). Consequently, if the entry is for example t-shirt, the search will be carried out on t-shirt without the need for an additional user action.

Disabling this auto-correction is possible by adding bypass_spellcheck member with the value true, such as in the example below:

Base query: `search_scope`

The query needs at least one member:

either non-empty scope corresponding to the requested category, supplied in your catalog by the field g:product_type

or non-empty scope_id corresponding to the requested category ID, supplied in your catalog by the field sf:scope_id

Examples:

Base query: `search_attributes`

Set algebra

This query is a combination of clauses with one of more subqueries on attributes.

If other base queries are present, the complete result is the intersection of the results for each base query.

During the calculation phase of search_attributes, if the item respects this clause, is marked as eligible.
The eligible items are a set of eligible items.
These sets are then merged according to the operator used thanks to set operations.

Supported clauses are:

Clause	Description
`must`	Eligible items respect all the clauses (intersection)
`should`	Articles found respect at least `minimum_should_match` clauses (union)

It is necessary to provide at least one clause.

In the following examples, for a better understanding, we consider that clauses are on different attributes.

Subqueries

`match_attribute_value`

This subquery returns articles whose targeted attribute has exactly the requested value.
The attribute must have only text values.

Examples

`match_attribute_range`

This subquery returns articles whose targeted attribute has a value in the targeted range.
The attribute must have only numeric values (integer or decimal).

match_attribute_range contains at least one clause among:

value_gt strictly bigger

value_gte bigger or equal

value_lt strictly smaller

value_lte smaller or equal

Examples

`search_attributes`

The search_attributes base query can itself be used as a clause in a search_attributes base query.

This query, counts among the maximum 32 clauses allowed.

Example of Boolean logic translations

Several clauses `must`

We are looking for an assortment of products that meet the intersection of the sets formed by clause_1, clause_2 and clause_3.

Translated into Boolean logic, an article is eligible if it respects each of the 3 clauses simultaneously:

clause_1 AND clause_2 AND clause_3

For example, the article is green in color, branded lambda, and on discount.
Consequently, excluded articles are excluded if they don't respect any of the clauses, or if they respect up to two clauses among the three.

Several clauses `should`

We are looking for an assortment of products that meet the union of the sets formed by clause_1, clause_2 and clause_3.

Translated into Boolean logic, an article is eligible if it respects at least one of the 3 clauses:

clause_1 OR clause_2 OR clause_3

For example, the article is green in color, or branded Lambda, or on discount.
Consequently, excluded articles are excluded because they are simultaneously neither green in color, nor branded Lambda , nor on discount.

Several clauses `must` and `should`

We are looking for an assortment of products that meet clause_1, clause_2, clause_3 and either to clause_4 or either to clause_5 or either to clause_6.

Translated into Boolean logic, an article is eligible if it respects the first 3 clauses and at least one of the three others:

(clause_1 AND clause_2 AND clause_3) AND (clause_4 OR clause_5 OR clause_6)

Notes:

minimum_should_match is 3, then this is equivalent to doing an AND on all the clauses: (clause_1 AND clause_2 AND clause_3) AND (clause_4 AND clause_5 AND clause_6)

minimum_should_match is 0, then this is equivalent to doing an AND on must clauses only: (clause_1 AND clause_2 AND clause_3)

minimum_should_match is 2, then this is equivalent to searching for the validation of 2 out 3 of the clauses of should:

(clause_1 AND clause_2 AND clause_3) AND ( (clause_4 AND clause_5) OR (clause_4 AND clause_6) OR (clause_5 AND clause_6))

Example of several clauses relating to the same attribute

We are looking for an assortment of products that either match clause_brand_1 or clause_brand_2 relating to the same attribute brand.
The following query would not be appropriate:

Indeed, in an usual commercial context, an article can't have two brands in the same time: the answer will be empty in this case.

To answer this question, you must perform the following query:

The articles are elected if they belong to either the set associated to clause_brand_1 or the set associated to clause_brand_2

Base query: `search_product`

This query, dedicated to retrieving one or multiple product sheets, expects a list of item identifier in the form of an array of character strings.

Example:

Base query: `context`

This request, dedicated to suggest actions, expects following parameters:

known_user, boolean value when user has a suggest-ready personalization profile.
This information is given by ActivityTrackingAPI at track creation.
If we set known_user to true where it is false, suggester will behave as known_user set to false

product_type is a focus to a product_type, value must be known in your catalog, related to g:product_type attribute.

product_url is a focus to a product, value (an url) value must be known in your catalog, related to g:link or g:canonical_link

Chapter dedicated to suggested_* actions details its usage and outputs.

Example:

Additional elements

`user_id` and `track_id`

The Sensefuel™ tag assigns a form of live identifier for each user, in order to learn from their behavior.

Important note:
If tag can be placed on your website, it's important to set up a coupling of user_id et track_id between the search API and the Sensefuel™ tag.

If tag can't be placed (example : mobile app) you will have to:

Generate a user_id (or use an available user_id),

Generate a track_id at each new session or app opening.

Reminder: this identifier is only technical and doesn't contain any personal information.

Otherwise, please refer to the ActivityTrackingAPI documentation for the management of user_id and track_id.

These parameters are obligatorily provided in query.

Call

`store_id`

This parameter applies the search query to a specific seller/dealer/store.
The value of this code parameter must be a string corresponding to a seller ID.

Call

Response

In case of use of the items module, data of each article will be completed with the following information:

sf:offer: contains data specific to the selected seller for the article presented within the product's vignet.
This information can be removed by explicitly adding "sf:offer": {"use": false} in the items module.

sf:stats: contains price-related data for the following contexts.
This information can be removed by explicitly adding "sf:stats": {"use": false} in the items module.

Stats contain following data:

no_seller_all_article : "catalog" price data for all product's articles

no_seller_current_article : "catalog" price data for the article presented within the product's vignet

current_seller_all_article : price data for the selected seller and all product's articles

current_seller_current_article : price data for the selected seller and the article presented within the product's vignet

all_seller_all_article : all sellers price data for all product's articles

all_seller_current_article : all sellers price data for the article presented in the product's vignet

`flavor`

This parameter let you apply a usage context when playing with suggested_* actions.
It allows us to choose an appropriate algorithm related to your use case.
With suggested_keywords action, only one value is available: search-home.
search-home should be use when a user will start a new search phase, when he focuses on search bar.
You may then suggest some useful keywords that should guide the user before he starts typing.

`segments`

This parameter allows you to scope response to a particular segmentation.

With this option you can fetch showcases inside the specified segmentation. For example a particular store id or a kind of user depending on data you send to us.

Call

`user_actions`

User actions are used to interpret typical user gestures performed on a result:

apply_filters: apply a filter

apply_scopes: select a scope

apply_spotlights: use a spotlight

apply_content_type: filter the content search on a specific content type (❕ only for Sensefuel MAX, explained on the section dedicated to contents)

apply_content_filters: apply a filter on contents (❕ only for Sensefuel MAX, explained on the section dedicated to contents)

These query modifiers are optional.

Effects on results

User actions will influence the results of the associated modules, according to the following correspondence table, in order to match the expectations of navigation on a set of products:

User action	Module
`apply_filters`	`facets`
`apply_scopes`	`scope_pages`
`apply_spotlights`	`spotlights`

User action: `apply_filters`

This user action will filter the search using the parameterized attributes (facets).

The relevant filter values according to the search made are provided automatically by the facet module (described below).

A logical OR is applied between the chosen values of the same attribute, while a logical AND will be applied between the different attributes.

The following call has the effect of restricting the search to sneakers (red OR blue) AND (Supersec brand) AND (in a price range of 9;99 to 49.99).

Example

A user searches for "sneakers" and uses following filters:

price selection between 9.99 and 49.99

selection of the Supersec brand

selection of the red and blue colors

In case of use of the facets module, if a filter is applied to a facet, the values returned in this facet are those of the base queries, by appliying all the other filters except this one.
Thereby, the user will still be able to reopen his result.

User action: `apply_scopes`

This user action applies a scope among those proposed via the scope pages module, in order to restrict the search to the selected scope.

The scopes correspond to the categories of your site.
The following call has the effect of restricting the search to only sneakers dedicated to shoes of the baby universe.
For the moment only one element is allowed in the "scopes" array. It must contain the path member, as sent in response to useing scope_pages module.

Example

A user searches for "sneakers" and uses scope "root > Baby > Shoes > Sneakers"

User action: `apply_spotlights`

This user action applies a spotlight among those proposed via the spotlightsmodule, in order to restrict the search to the selected spotlight.

For the moment only one element is allowed in the "spotlights" array.
It must imperatively contain the identifier of the spotlight in the form of a string.
This identifier is provided within the previous answer.

Example

A user searches for "sneakers" and uses spotlight "spotlight_brand_4"

Catalog modules

With the modules, you will obtain, for a search, the different types of desired results.
The basic module is items: it allows to retrieve articles corresponding to an expression entered by a user.

Module `items`

This module allows to obtain the articles corresponding to a search (query).

Call options

Call options	Description	Type	Default value
`from`	Index of the first product to return, for pagination	Positive integer	0
`size`	Maximum number of products, for pagination	Positive integer	60
`fields`	List of desired attributes in articles	Array of strings ¹	all configured attributes
`variants_fields`	List of desired attributes for items of a product	Array of strings ²	all configured attributes
`sort`	Replaces the sort by relevance (by default) with another sort	Object containing the attribute and direction. The only allowed values are accessible via a call to the settings of the API ³	none

¹ If the field is passed with an empty array as value, no attribute will be returned.

² If the field is passed with an empty array as value, no attribute will be returned. Usable only in the case of a catalog with product grouping (g: item_group_id filled in).

³ To return to sort by relevance, do not provide field sort

Call

Response structure

In response, the items module will contain the following fields:

| Field | Description | Type |
| ----------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | --- |
| total | Total number of products matching the query | Positive integer |
| parts | List of products corresponding to the query | Array of objects containing the list of attributes parameterized or explicitly requested (fields) |
| forced_zr | Optional: response was enforced to 0 results | Boolean |
| source | Optionnel: indique si la réponse vient du flux offre ou du flux catalogue | String : "offers" ou "catalog" | |

Response

Module `facets`

This module provides the facets available and linked to a search (query).

Call options

Options d'appel	Description	Type	Default value
`fields`	List of desired attributes to filter	Array of character strings ¹	All configured attributes

¹ If the field is passed with an empty array as value, no attribute will be returned.

Call

Response structure

In response, the facets module will contain the following fields :

Field	Description	Type
`parts`	Array of elements, each of them has a unique member of the attribute name set as facet.	Array of elements

The usage depends on the type value specified for each facet:

Response structure

In response, the spotlights module will provide an array with eligible spotlights.
You need to know that the spotlights module response will be empty if you don't ask for items module in your request.

Response

The matchedParts field contains spotlights that specifically match the user's search or navigation criteria. The parts field contains spotlights that are not contextualised to the current search.
Currently, use of the parts field is deprecated.

Response

Module `spell_check`

spell_check is a utility module.
This module retrieves the corrected term that has been automatically used by Sensefuel.

Examples of use

The user is informed of a correction of his entry. If it does not satisfy him, he can restart his search exactly on the entry without automatic correction.
It is possible to replay the original search via this module and the bypass_spellcheck member to true as seen in the terms of the query.

Call triggering a self-correction

Call

Response

Call not triggering self-correction

Call

Response

Module `bag`

bag is a utility module.
Its main feature is to return to the identical, within the response, the content passed during the call.

Example of use

When successive calls to the API are made (user hits), the responses order obtained may be different (depending on the processing time, the weight, the quality of the network, etc.).
The bag can in this case be used to transmit a key during the call (generated by you, for example a timestamp) which will allow you in return to identify the response to be processed.

Call

Response

Module `statistics`

statistics is a utility module, it provides information related to the execution of the query.

To retrieve this information, simply add this module when calling as an empty object but not null.

Call

Response

Module `tracking`

Preamble

For a given user, each visit are associated to different identifiers and are associated with each other by a user identifier.
These identifiers may come from:

your own user identification system ;

these identifiers can be generated during the creation of a session using our ActivityTrackingAPI, which you must store;

our tag if present on your site using a cookie named 126ada9239a744ae83a6173ff0bf81ed. As this cookie can evolve (add / remove key), it is important to systematically browse all of its content in order to retrieve all the key / value pairs.

Warning: these session and user identifiers cannot contain any personal information.

Call

Response

In the example above, we note:

the return of the only track_id member,

the appearance of the payload member, fundamental for the user's real-time behavioral management.

Payload role

Its role is to freeze the utilitarian understanding in a certain state; it is imperative to guarantee the consistency of results when, for example, pagination, ...

How to manage the payload ?

For any call:

user_id and track_id are mandatory

For any answer received:

If no payload is provided: you must destroy any trace of payload associated with the track_id (typically in session store).

If a payload is provided to you: you must systematically enter the new payload value associated with the track_id (typically in session store).

Note: If you have front multiple without sticky-session and a cache system, it must be global to ensure proper tracking.

Call

Module `settings`

Whether explicitly requests or not, the settings module is always present in case of a valid answer.
Its id attribute carries a unique value which represents the parameters necessary for the interpretation of the results.
If there is a change in these parameters, this value will change.
In this case, it is necessary to retrieve the new settings using the settings action to properly interpret the results and retrieve the new id.

Call

Response

Module `showcases`

This module allows you to fetch grouped products "showcases" that feat with realized search action.

Call

There are 2 methods to request showcases.

You can simply call the module "showcases" to fetch all configured types of showcases. The max number of products is the default configured value.

Example :

If you want to fetch specific types of showcases, you need to specify the "type" array property. If it's empty, the API will return nothing. For example, if you specify the "BANNER" type, it will only return showcases of type "BANNER". In this case, you have to request a specific number of products per showcases type.

Example :

Call options

*Note: No member is required, only the presence of the module as an empty object ({}) is sufficient for itself.*

Call options	Description	Type	Default value
`fields`	List of desired attributes in articles	Array of strings ¹	all configured attributes
`variants_fields`	List of desired attributes for items of a product	Array of strings ²	all configured attributes

¹ If the field is passed with an empty array as value, no attribute will be returned.

² If the field is passed with an empty array as value, no attribute will be returned. Usable only in the case of a catalog with product grouping (g: item_group_id filled in).

Additional informations

Showcases template is defined like this :

BANNER corresponding to VISUAL template in Sensefuel back office.

FULL_PRODUCT corresponding to SPONSORED template in Sensefuel back office.

MANUAL_RANKING corresponding to NEUTRAL template in Sensefuel back office.

Response structure

The response for module showcases will provide an object with an array of type

Response

Importante note: contents are only available with the Sensefuel MAX product. Elements described in this section therefore only concern users of the Sensefuel MAX solution, with contents.

To access the contents, it is necessary to pass a base query of terms type.
The returned contents will match to the requested expression.
Types of contents correspond to the types defined in schema.org.

Module `contents_kicker`

This module provides suggestions of types of contents corresponding to the expression requested by the use of the base query terms.

Call options

Call option	Description	Type	Default value
`size`	Maximum number of contents to suggest per type of content	Positive integer	1

The provided contents correspond to the top size, sorted by relevance, for each type of content.

Call

Response structure

In response, contents_kicker module will contain the following fields:

Fields	Description	Type
`total`	Total number of contents corresponding to the query, all types included	Positive integer
`found_types`	List of types of contents responding to `expression`	Array of object FoundContentTypeObject containing content types and related content suggestions
`FoundContentTypeObject.total`	Total number of contents for the content type found	Positive integer
`FoundContentTypeObject.type`	Name of the content type found	String
`FoundContentTypeObject.top_hits`	List of suggested contents for the found type	Array of objects representing the contents to be returned, of considered `type`

Response

Module `contents_items`

This module provides contents corresponding to the expression requested by the use of the base query terms.

Call options

Call option	Description	Type	Default value
`from`	Index of the first content to return, for pagination	Positive integer	0
`size`	Maximum number of contents to return, for pagination	Positive integer	16

Provided contents are sorted by relevance.

Call

Response structure

In response, the contents_items module will contain the following fields:

Fields	Description	Type
`total`	Total number of contents corresponding to the query, all types included	Positive integer
`parts`	List of contents corresponding to `expression`	Array of objects representing the contents to be returned. The content type is specified with the special attribute `@type`

Response

User action: `apply_content_type`

Description

This user action allows to filter the content search on a specific type of content, typically those returned by the use of contents_kicker module, and applies to the results of content_items module only.

Only one value can be specified.

Example

A user is looking for "machines" and he only requests "Review" type content.

Example of response

Module `contents_facets`

This module provides facets on contents corresponding to the expression requested by the use of the base query terms.
These facets are declined for each type of content responding to the query.

Call options

No option

Call

Response structure

In response, the contents_facets module will contain the following fields:

Fields	Description	Type
`parts`	List of facets responding to `expression`	Array of objects FoundContentFacet representing the applicable facets
`FoundContentFacet.facet_name`	Facet name in `Type.Attribut` format	String
`FoundContentFacet.score`	Facet importance score	Integer
`FoundContentFacet.count`	Nomber of contents that can respond to the facet	Integer
`FoundContentFacet.parts`	Array of objects representing each possible `value` of the facet, with an associated`score` of importance and `count` of associated contents	Array of objects

Response

User action: `apply_content_filters`

Description

This user action is used to filter the search on contents using parameterized attributes (facets).

The relevant filter values according to the search made are automatically provided by the contents_facets module describe above.

A logical OR is applied between the chosen values of a same attribute, while a logical AND will be applied between the different attributes.

Example

A user is looking for "machines" and uses the following filter:

selection of the "Professionals" audience on the "NewsArticle.audience" attribute

Example of response

In case of use of the contents_facets module, if we apply a filter on a facet, the values returned in this facet are those of the requested expression applying all other filters except this one.
So this user can still reopen his result.

Example of response

Suggestion modules

Module `suggested_keywords`

This module retrieves a list of keywords/products from a context.

Call options

Call options	Description	Type	Default value
`size`	Maximum number of keywords	Positive integer	4
`suggested_products`	Products suggestions related to each keywords (optional)	Object	undefined
`suggested_products.size`	Maximum number of products	Positive integer	4
`suggested_products.fields`	List of desired attributes in articles	Array of strings ¹	all configured attributes
`suggested_products.variants_fields`	List of desired attributes for items of a product	Array of strings ²	all configured attributes

In response, the suggested_shortcuts module will provide an array with size shortcuts maximum. It will contain the following fields:

Fields	Description	Type
`parts`	List of shortcuts data matched by keywords	Array of objects Shortcut containing data about the shortcut
`Shortcut.id`	Id of the shortcut	String
`Shortcut.label`	Label of the shortcut	String
`Shortcut.url`	Redirect URL	String
`Shortcut.promotion`	"default", "preferred" or "pinned" according to the "promote" module configuration	String
`Shortcut.score`	Relevance score	Float
`Shortcut.matched_keywords`	Number of keywords matched by the search terms	Integer
`keywords`	List of keywords corresponding to the query	String[]

Response

Actions

You will find below the description of different possible actions, and queries and modules available.

`search` action

The search action is used to obtain the results associated with (among other things) an expression searched by a user.

Base query	Use
`terms`	Yes - mandatory
`search_scope`	Yes
`search_attributes`	Yes
`search_product`	No
`context`	No
`store_id`	Yes
`user_id`	Yes - mandatory
`track_id`	Yes - mandatory
`flavor`	No
`segments`	Yes

Module	Use
`items`	Yes
`facets`	Yes
`scope_pages`	Yes
`univers_pages`	Yes
`spotlights`	Yes
`acp`	Yes
`references`	Yes
`shortcuts`	Yes
`contents_kicker`	Yes
`contents_items`	Yes
`contents_facets`	Yes
`suggested_keywords`	No
`suggested_scope_pages`	No
`suggested_spotlights`	No
`suggested_shortcuts`	No
`spell_check`	Yes
`bag`	Yes
`statistics`	Yes
`tracking`	Yes
`showcases`	Yes
`settings`	By default

`user_actions`	Use
`apply_filters`	Yes
`apply_scopes`	Yes
`apply_spotlights`	Yes
`apply_content_type`	Yes
`apply_content_filters`	Yes

`navigation` action

The navigation action is used to obtain articles contained in a category.

Base query	Use
`terms`	No
`search_scope`	Yes - mandatory
`search_attributes`	Yes
`search_product`	No
`context`	No
`store_id`	Yes
`user_id`	Yes - mandatory
`track_id`	Yes - mandatory
`flavor`	No
`segments`	Yes

Module	Use
`items`	Yes
`facets`	Yes
`scope_pages`	Yes
`univers_pages`	Yes
`spotlights`	Yes
`acp`	Yes
`references`	No
`shortcuts`	No
`contents_kicker`	No
`contents_items`	No
`contents_facets`	No
`suggested_keywords`	No
`suggested_scope_pages`	No
`suggested_spotlights`	No
`suggested_shortcuts`	No
`spell_check`	No
`bag`	Yes
`statistics`	Yes
`tracking`	Yes
`showcases`	Yes
`settings`	By default

`user_actions`	Use
`apply_filters`	Yes
`apply_scopes`	No
`apply_spotlights`	Yes
`apply_content_type`	No
`apply_content_filters`	No

`landing_page` action

The landing page action is used to obtain an assortment of items that share common characteristics.

Base query	Use
`terms`	No
`search_scope`	Yes
`search_attributes`	Yes - mandatory
`search_product`	No
`context`	No
`store_id`	Yes
`user_id`	Yes - mandatory
`track_id`	Yes - mandatory
`flavor`	No
`segments`	Non

Module	Use
`items`	Yes
`facets`	Yes
`scope_pages`	Yes
`univers_pages`	Yes
`spotlights`	Yes
`acp`	Yes
`references`	No
`shortcuts`	No
`contents_kicker`	No
`contents_items`	No
`contents_facets`	No
`suggested_keywords`	No
`suggested_scope_pages`	No
`suggested_spotlights`	No
`suggested_shortcuts`	No
`spell_check`	No
`bag`	Yes
`statistics`	Yes
`tracking`	Yes
`showcases`	Non
`settings`	By default

`user_actions`	Use
`apply_filters`	Yes
`apply_scopes`	Yes
`apply_spotlights`	Yes
`apply_content_type`	No
`apply_content_filters`	No

`product_selection` action

The product selection action is used to obtain an assortment of items that share common characteristics.

Base query	Use
`terms`	No
`search_scope`	Yes
`search_attributes`	Yes - mandatory
`search_product`	No
`context`	No
`store_id`	Yes
`user_id`	Yes - mandatory
`track_id`	Yes - mandatory
`flavor`	No
`segments`	Non

Module	Use
`items`	Yes
`facets`	Yes
`scope_pages`	Yes
`univers_pages`	Yes
`spotlights`	Yes
`acp`	Yes
`references`	No
`shortcuts`	No
`contents_kicker`	No
`contents_items`	No
`contents_facets`	No
`suggested_keywords`	No
`suggested_scope_pages`	No
`suggested_spotlights`	No
`suggested_shortcuts`	No
`spell_check`	No
`bag`	Yes
`statistics`	Yes
`tracking`	Yes
`showcases`	Non
`settings`	By default

`user_actions`	Use
`apply_filters`	Yes
`apply_scopes`	Yes
`apply_spotlights`	Yes
`apply_content_type`	No
`apply_content_filters`	No

`product_sheet` action

The product sheet action is used to retrieve data associated to a product.

Base query	Use
`terms`	No
`search_scope`	No
`search_attributes`	No
`search_product`	Yes - mandatory
`context`	No
`store_id`	Yes
`user_id`	Yes - mandatory
`track_id`	Yes - mandatory
`flavor`	No
`segments`	Non

Module	Use
`items`	Yes
`facets`	No
`scope_pages`	No
`univers_pages`	No
`spotlights`	No
`acp`	No
`references`	No
`shortcuts`	No
`contents_kicker`	No
`contents_items`	No
`contents_facets`	No
`suggested_keywords`	No
`suggested_scope_pages`	No
`suggested_spotlights`	No
`suggested_shortcuts`	No
`spell_check`	No
`bag`	Yes
`statistics`	Yes
`tracking`	Yes
`showcases`	Non
`settings`	By default

`user_actions`	Use
`apply_filters`	No
`apply_scopes`	No
`apply_spotlights`	No
`apply_content_type`	No
`apply_content_filters`	No

Action `suggested_keywords`

suggested_keywords action let you get suggested keywords.
Each suggest module result is provided by keywords as they would be played individually.
Only one flavor is currently available : search-home
search-home should be use when a user will start a new search phase, when he focuses on search bar.
You may then recommend some useful keywords that should guide the user before he starts typing.

Base query	Use
`terms`	No
`search_scope`	No
`search_attributes`	No
`search_product`	No
`context`	Yes - mandatory
`store_id`	Yes
`user_id`	Yes - mandatory
`track_id`	Yes - mandatory
`flavor`	Yes
`segments`	Non

Module	Use
`items`	No
`facets`	No
`scope_pages`	No
`univers_pages`	No
`spotlights`	No
`acp`	No
`references`	No
`shortcuts`	No
`contents_kicker`	No
`contents_items`	No
`contents_facets`	No
`suggested_keywords`	Yes - Mandatory
`suggested_scope_pages`	Yes
`suggested_spotlights`	Yes
`suggested_shortcuts`	Yes
`spell_check`	No
`bag`	Yes
`statistics`	Yes
`tracking`	Yes
`showcases`	Non
`settings`	By default

`user_actions`	Use
`apply_filters`	No
`apply_scopes`	No
`apply_spotlights`	No
`apply_content_type`	No
`apply_content_filters`	No

Action `zero_results`

zero_results action let you get suggested keywords when no results are found for given keywords in terms query.
Each suggest module result is provided by keywords as they would be played individually.

Base query	Use
`terms`	Yes - mandatory
`search_scope`	No
`search_attributes`	No
`search_product`	No
`context`	No
`store_id`	Yes
`user_id`	Yes - mandatory
`track_id`	Yes - mandatory
`flavor`	Yes
`segments`	Non

Module	Use
`items`	No
`facets`	No
`scope_pages`	No
`univers_pages`	No
`spotlights`	No
`acp`	No
`references`	No
`shortcuts`	No
`contents_kicker`	No
`contents_items`	No
`contents_facets`	No
`suggested_keywords`	Yes - Mandatory
`suggested_scope_pages`	Yes
`suggested_spotlights`	Yes
`suggested_shortcuts`	Yes
`spell_check`	No
`bag`	Yes
`statistics`	Yes
`tracking`	Yes
`showcases`	Non
`settings`	By default

`user_actions`	Use
`apply_filters`	No
`apply_scopes`	No
`apply_spotlights`	No
`apply_content_type`	No
`apply_content_filters`	No

`settings` action

The settings contain information related to the settings of certain features (example: user sorting, images related to spotlights, labels, ...) and useful for constructing results.

HTTP request

GET https://api.sensefuel.live/discovery/{site-uuid}/settings

URL parameters

Name	Description
`site-uuid`	String -- site ID

Response body

If the request is successful, the response body is composed of two members:

id: an unique value representing the settings. If settings change, the ID changes. You have to store it to know if you can correctly interpreter the results (this id is systematically returned in the settings module). If it changes, you have to call the settings action.

settings: an object containing the settings of certain features

Example:

{
    "id": "a83dbe545c0b4240a0beaf355f0f088f",
    "settings": {
        "ranking": [
            {
                "field": "sf:isDiscount",
                "display": "Promotions",
                "order": "desc"
            },
            {
                "field": "sf:isNew",
                "display": "Nouveautés",
                "order": "desc"
            },
            {
                "field": "sf:price",
                "display": "Prix descendant",
                "order": "desc"
            },
            {
                "field": "sf:price",
                "display": "Prix ascendant",
                "order": "asc"
            }
        ]
    }
}

Content of settings

The settings object contains settings of following features:

fields: a list of available attributes for base queries

ranking: a list of available attributes in the sort module

spotlights: the spotlight configuration allowing you to interpret the results of the spotlights and suggested_spotlights modules

shortcuts: the shortcut configuration allowing you to interpret the results of the shortcuts and suggested_shortcuts modules

showcases: la configuration des showcases vous permettant de connaître les types de showcases existant chez vous.

This information comes from the latest indexation made available.

Details of `fields`

The fields object contains a list of available attributes for base queries.
Only attributes linked to articles are considered.

field indicates the name of the attribute as it is present in the article.
type field indicates the type of the attributes as it was read and interpreted in the catalog feed.
labels field gives labels to display (setup in Sensefuel backoffice).
filterable indicates that the field can be used as a filter.
search_attributes indicates that the field can be queried using search_attributes.

We notice 3 available types:

string

long

double
When reading the catalog feed, the types are inferred based on the first documents read and bearing these attributes (in alphabetical order on the g:id field)

Example

A query made on an unavailable attribute will be rejected.

Detail of `ranking`

The ranking object contains a list of available attributes for sort module. this module can be used in the items module to replace sort by relevance (sort by default).

field indicates the name of the attribute as it is present in the article.
display field indicates the name of the attributes as it will be displayed.
order field indicates the direction of the sort performed on this attribute (descending or ascending).

Example

A query made on an unavailable attribute will be rejected.

Details of `spotlights`

The spotlight object contains the list of spotlight you have configured, as well as details of these spotlights, in order to be able to correctly display them.
Each key is a spotlight identifier (which is also returned by the response of the spotlights module)

Fields	Description
display.logo	Link to brand logo (null if event spotlight)
display.title	Spotlight title to display
display.description	Spotlight description to display if event spotlight
display.background	Spotlight background image link
display.background_color	Spotlight background color
display.background_position	Spotlight background position
display.alternative_background_image	Spotlight background image alt link
display.alternative_background_position	Spotlight background alt image position
label	Spotlight technical name
promotion	Spotlight promotion (pinned or preferred)
products_count	Number of products in the spotlight if applied alone
articles_count	Number of articles in the spotlight if applied alone

Exemple

A query made on an unavailable spotlight id will fail or ignored depending on the module.

Détails of `shortcuts`

The shortcuts object contains the list of promoted shortcuts you have configured, as well as details of these shortcuts, in order to be able to correctly display them.

Fields	Description
id	Shortcut technical name
url	Link to shortcut page
label	Shortcut title to display
promotion	Shortcut promotion (pinned or preferred)

Example

{
    "id": "a83dbe545c0b4240a0beaf355f0f088f",
    "settings": {
        "shortcuts": [
            {
                "id": "Shop",
                "label": "Find a shop",
                "url": "https://shop.example.com",
                "promotion": "pinned"
            }
        ]
        // [...]
    }
}

Détails of `showcases`

The showcases object contains the list of showcases types you have configured.

Example

{
    "id": "a83dbe545c0b4240a0beaf355f0f088f",
    "settings": {
        "showcases": ["FULL_PRODUCT", "MANUAL_RANKING", "BANNER"]
    }
}

Documentation

General concept#

Objectives#

Operation#

General purpose#

Instant response#

Behavioral analysis#

Individualized response#

Retrieving the User ID and the Session ID via the JavaScript tag#

Tracking features of the Sensefuel JavaScript tag#

Retrieving the User ID#

Accessing the Sensefuel JavaScript Interface#

Retrieving the Session ID#

Precaution#

Using the User and Session IDs with Sensefuel APIs#

Dynamic Client-side Calls (Client-side Rendering)#

Server-side Calls (Server-side Rendering)#

User ID Updates#

Available actions#

Base queries#

Calls modularization#

user_actions#

Effects on results#

Example#

Access#

Call format#

Response format#

Errors management#

Exchange structure#

HTTP request#

URL parameters#

Request body#

Response body#

Query#

Base query: terms#

Base query: search_scope#

Base query: search_attributes#

Set algebra#

Subqueries#

match_attribute_value#

Examples#

match_attribute_range#

Examples#

search_attributes#

Example of Boolean logic translations#

Several clauses must#

Several clauses should#

Several clauses must and should#

Example of several clauses relating to the same attribute#

Base query: search_product#

Base query: context#

Additional elements#

user_id and track_id#

Call#

store_id#

Call#

Response#

flavor#

segments#

Call#

user_actions#

Effects on results#

User action: apply_filters#

Example#

User action: apply_scopes#

Example#

User action: apply_spotlights#

Example#

Catalog modules#

Module items#

Call options#

Call#

Response structure#

Response#

Module facets#

Call options#

Call#

Response structure#

Response#

Module universe_pages#

General concept

Objectives

Operation

General purpose

Instant response

Behavioral analysis

Individualized response

Retrieving the User ID and the Session ID via the JavaScript tag

Tracking features of the Sensefuel JavaScript tag

Retrieving the User ID

Accessing the Sensefuel JavaScript Interface

Retrieving the Session ID

Precaution

Using the User and Session IDs with Sensefuel APIs

Dynamic Client-side Calls (Client-side Rendering)

Server-side Calls (Server-side Rendering)

User ID Updates

Available actions

Base queries

Calls modularization

`user_actions`

Effects on results

Example

Access

Call format

Response format

Errors management

Exchange structure

HTTP request

URL parameters

Request body

Response body

Query

Base query: `terms`

Base query: `search_scope`

Base query: `search_attributes`

Set algebra

Subqueries

`match_attribute_value`

Examples

`match_attribute_range`

Examples

`search_attributes`

Example of Boolean logic translations

Several clauses `must`

Several clauses `should`

Several clauses `must` and `should`

Example of several clauses relating to the same attribute

Base query: `search_product`

Base query: `context`

Additional elements

`user_id` and `track_id`

Call

`store_id`

Call

Response

`flavor`

`segments`

Call

`user_actions`

Effects on results

User action: `apply_filters`

Example

User action: `apply_scopes`

Example

User action: `apply_spotlights`

Example

Catalog modules

Module `items`

Call options

Call

Response structure

Response

Module `facets`

Call options

Call

Response structure

Response

Module `universe_pages`

Call options