This documentation is generated by Sensefuel.
AI Search & Product Discovery platform that makes ecommerce search personal.
Documentation
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 strenghs 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 is 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:
window.sensefuel_a038457e.trackingInfo().user.id;
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:
window.sensefuel_a038457e.trackingInfo().session.id;
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_a038457einterface to become available. - Retrieve the user ID:
const userId = window.sensefuel_a038457e.trackingInfo().user.id;
- Or retrieve the session ID:
const sessionId = window.sensefuel_a038457e.trackingInfo().session.id;
- Pass these identifiers along to our
DiscoveryorRecommendAPIs.
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:
document.cookie = `sensefuel_user_id=${
window.sensefuel_a038457e.trackingInfo().user.id
}; path=/; SameSite=Lax`;
- Similarly, you can transmit the session ID by storing it in a first-party cookie:
document.cookie = `sensefuel_session_id=${window.sensefuel_a038457e.trackingInfo().session.id}; path=/; SameSite=Lax`;
- You can transmit both IDs through the first-party cookie:
document.cookie = `sensefuel_user_id=${window.sensefuel_a038457e.trackingInfo().user.id}; sensefuel_session_id=${window.sensefuel_a038457e.trackingInfo().session.id}; path=/; SameSite=Lax`;
- 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:
searchnavigationlanding_pageproduct_selectionproduct_sheetsuggested_keywordszero_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/contentssearch_scope: scopes in which articles are ventilatedsearch_attributes: article characteristicsearch_product: article IDs or referencescontextandflavor: for suggestion, call context and usage descriptionsearch_id: article ID
-->
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 queryfacets: recovery of filters and filter values related to the articlesscope_pages: proposal of scopes associated with articlesunivers_pages: proposal of universes associated with articlesspotlights: spotlights associated with articlesacp: completion suggestions of the search termreferences: recovery of articles that match the query by their reference(s)shortcuts: recovery of redirects that match the querycontents_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, spotlightssuggested_keywords,suggested_scope_pages,suggested_spotlightsandsuggested_shortcuts: get search, scopes, spotlights and shortcuts suggestionsshowcases: 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 searchbag: returns information sent in the API callstatistics: 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 filterapply_scopes: select a scopeapply_spotlights: use a spotlightapply_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 (
termsquery) - articles recovery (
itemsmodule); - recovery of available colors (
facetsmodule).
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 (
termsquery,itemsmodule); - with the red color applied (
apply_filtersuser action); - articles recovery (
itemsmodule); - recovery of available colors (
facetsmodule).
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:
{
"error": {
"message": "Bad Request. query.terms must contain a non-empty expression when provided."
}
}
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 -- Side 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:
{
"query" : {
"terms" : {
"expression" : "t-shirt"
}
},
"user_actions": {
"apply_filters": {
"g:brand" : ["Supersec"]
}
},
"modules" : {
"items" : {
}
}
}
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.
{
"modules" : {
"items" : {
"parts": [
{
"g:id": "502598_0480_XL",
"g:title": "Knitted T-shirt",
"sf:pr": 0
},
{
"g:id": "494351_2230_T1,T2",
"g:title": "V-neck T-shirt",
"sf:pr": 0
}
],
"total": 416,
"source": "offers"
}
}
}
Query
Query is an object that contains base queries and query modifiers.
Base queries are:
terms: searches for the given termssearch_scope: searches in a given categoriessearch_attributes: searches in the characteristics of an articlesearch_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.
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 :
{
"query": {
"terms": {
"expression": "t-shirt"
}
}
//[...]
}
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:
{
"query": {
"terms": {
"expression": "t-shirt",
"bypass_spellcheck": true
}
}
//[...]
}
Base query: search_scope
The query needs at least one member:
- either non-empty
scopecorresponding to the requested category, supplied in your catalog by the fieldg:product_type - or non-empty
scope_idcorresponding to the requested category ID, supplied in your catalog by the fieldsf:scope_id
Examples:
{
"query": {
"search_scope": {
"scope": "Man > Jeans"
}
}
//[...]
}
{
"query": {
"search_scope": {
"scope_id": "cat_4224"
}
}
//[...]
}
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
{
"query": {
"search_attributes": {
"must": [
{
"match_attribute_value": {
"field": "g:availability",
"value": "in stock"
}
}
]
}
}
//[...]
}
match_attribute_range
This subquery returns articles whose targeted attribute has a value in the taregeted range.
The attribute must have only numeric values (integer or decimal).
match_attribute_range contains at least one clause among:
value_gtstrictly biggervalue_gtebigger or equalvalue_ltstrictly smallervalue_ltesmaller or equal
Examples
{
"query": {
"search_attributes": {
"must": [
{
"match_attribute_range": {
"field": "c:price_numerical",
"value_gte": 10,
"value_lt": 100
}
}
]
}
}
//[...]
}
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 assorment of products that meet the intersection of the sets formed by clause_1, clause_2 and clause_3.
{
"query": {
"search_attributes": {
"must": [
{// clause_1},
{// clause_2},
{// 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.
{
"query": {
"search_attributes": {
"should": [
{// clause_1},
{// clause_2},
{// clause_3},
],
"minimum_should_match": 1
}
}
//[...]
}
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.
{
"query": {
"search_attributes": {
"must": [
{// clause_1},
{// clause_2},
{// clause_3},
],
"should":[
{// clause_4},
{// clause_5},
{// clause_6},
],
"minimum_should_match": 1
}
}
//[...]
}
Translated into Boolean logic, an article is eligible if he 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_matchis 3, then this is equivalent to doing anANDon all the clauses:(clause_1 AND clause_2 AND clause_3) AND (clause_4 AND clause_5 AND clause_6)minimum_should_matchis 0, then this is equivalent to doing anANDonmustclauses only:(clause_1 AND clause_2 AND clause_3)minimum_should_matchis 2, then this is equivalent to searching for the validation of 2 out 3 of the clauses ofshould:(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:
{
"query": {
"search_attributes": {
"must": [
{// clause_brand_1},
{// clause_brand_2}
]
}
}
//[...]
}
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 quetion, you must perform the following query:
{
"query": {
"search_attributes": {
"should": [
{// clause_brand_1},
{// clause_brand_2}
]
}
}
//[...]
}
The articles are elected if they bellong 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:
{
"query": {
"search_product": {
"ids": ["142241"]
//"references": ["142241"]
}
//[...]
}
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 setknown_usertotruewhere it isfalse, suggester will behave asknown_userset tofalseproduct_typeis a focus to a product_type, value must be known in your catalog, related tog:product_typeattribute.product_urlis a focus to a product, value (an url) value must be known in your catalog, related tog:linkorg:canonical_link
Chapter dedicated to suggested_* actions details its usage and outputs.
Example:
{
"query": {
"context": {
"known_user": true,
"product_type": "Kid > Tshirt"
},
}
//[...]
}
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_idat 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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query" : {
"terms" : {
"expression" : "sneakers"
},
"user_id" : "edc85853-SAMPLE-ID-329f706a626f",
"track_id" : "00c4a697-SAMPLE-ID-030d69ba96dc"
}
//[...]
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query" : {
"terms" : {
"expression" : "sneakers"
},
"store_id": "dummySeller"
}
//[...]
}
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 theitemsmodule. -
sf:stats: contains price-related data for the following contexts.
This information can be removed by explicitly adding"sf:stats": {"use": false}in theitemsmodule.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
-
{
"modules" : {
"items" : {
// Array of matching products
"parts": [
{
//[...]
"sf:pr": 0,
"sf:offer": {
"sf:previous_price": 99,
"sf:price": 89,
"g:quantity": "1",
"sf:isDiscount": true
},
"sf:stats": {
"no_seller_all_article": {
"min_price": 99,
"max_price": 99,
"sellers_count": 0,
"discounted_sellers_count": 0,
"articles_count": 7,
"discounted_articles_count": 0
},
"no_seller_current_article": {
"min_price": 99,
"max_price": 99,
"sellers_count": 0,
"discounted_sellers_count": 0,
"articles_count": 1,
"discounted_articles_count": 0
},
"current_seller_all_article": {
"min_price": 89,
"max_price": 89,
"sellers_count": 1,
"discounted_sellers_count": 1,
"articles_count": 7,
"discounted_articles_count": 7
},
"current_seller_current_article": {
"min_price": 89,
"max_price": 89,
"sellers_count": 1,
"discounted_sellers_count": 1,
"articles_count": 1,
"discounted_articles_count": 1
},
"all_seller_all_article": {
"min_price": 69,
"max_price": 99,
"sellers_count": 23,
"discounted_sellers_count": 21,
"articles_count": 7,
"discounted_articles_count": 7
},
"all_seller_current_article": {
"min_price": 69,
"max_price": 99,
"sellers_count": 22,
"discounted_sellers_count": 21,
"articles_count": 1,
"discounted_articles_count": 1
}
}
//[...]
},
//[...]
],
// Total items count
"total": 416,
"source": "offers"
}
}
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query" : {
"terms" : {
"expression" : "sneakers"
},
"store_id": "dummySeller",
"segments": [
{
"key": "isLogged",
"value": "true"
}
]
}
//[...]
}
user_actions
User actions are used to interpret typical user gestures performed on a result:
apply_filters: apply a filterapply_scopes: select a scopeapply_spotlights: use a spotlightapply_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
{
"query" : {
"terms" : {
"expression" : "sneakers"
}
},
"user_actions": {
"apply_filters": {
"sf:price" : ["9.99;49.99"],
"g:brand" : ["Supersec"],
"sf:semanticColor" : ["red", "bleu"]
}
},
//[...]
}
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 allt he 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"
{
"query" : {
"terms" : {
"expression" : "sneakers"
}
},
"user_actions": {
"apply_scopes":[
{
"path": "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"
{
"query" : {
"terms" : {
"expression" : "sneakers"
}
},
"user_actions": {
"apply_spotlights": ["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 1 | all configured attributes |
variants_fields | List of desired attributes for items of a product | Array of strings 2 | 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 3 | none |
1 If the field is passed with an empty array as value, no attribute will be returned.
2 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).
3 To return to sort by relevance, do not provide field sort
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"items" : {
// Returns products from the first one (index "0-based")
"from" : 0,
// Returns maximum 12 products
"size" : 12,
// Returns only these three fields (if exists) per product
"fields" : ["g:id","g:link", "g:title"],
// Sort by price, from the cheaper to the most expensive
"sort" : { "field": "sf:price", "order" : "asc"}
}
}
}
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
{
"modules" : {
"items" : {
// Array of matching products
"parts": [
{
//[...]
"g:id": "502598_0480",
"g:link": "https://example.com/products/502598_0480",
//[...]
"g:title": "High blue sneaker"
//[...]
"sf:pr": 0
},
{
//[...]
"g:id": "494351_2230",
"g:link": "https://example.com/products/494351_2230",
//[...]
"g:title": "Black sneaker"
//[...]
"sf:pr": 0
}
//[...]
],
// Total items count
"total": 416,
"source": "offers"
}
}
}
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 1 | All configured attributes |
1 If the field is passed with an empty array as value, no attribute will be returned.
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"facets" : { // Module that provides list of available facets
"fields" : ["g:brand","sf:price"]// Returns only facets for these two fields.
}
}
}
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:
- The generic type is
multivalued: it provides an array of applicable values with for each of them the number of associated elements. - The
slidertype is suitable for constructing price filters as a range of values. Its different terminals prevent a selection that will not return any results.
Response
{
"modules" : {
"facets" : {
"parts": [
{
"g:brand": {
"pr": 0,
"score": 2,
"type": "multivalued",
"buckets": [
{
"key": "Google",
"pCount": 925,
"pr": 0,
"score": 4
},
{
"key": "Amazon",
"pCount": 703,
"pr": 0,
"score": 3
},
{
"key": "PS4",
"pCount": 15,
"pr": 0,
"score": 2
},
{
"key": "PC",
"pCount": 10,
"pr": 0,
"score": 1
}
]
},
},
{
"sf:price": {
"type": "slider",
"pr": 0,
"score": 1,
"boundaries": {
"from_min": 1.99, // minimum price without facet
"from_significant": 16.99, // minimum price with facets
"from": 16.99, // current value of minimum cursor
"to": 149.99, // current value of maximum cursor
"to_significant": 149.99, // maximum price with facets
"to_max": 699.99 // minimum price without facet
},
"max_count": 1643
}
}
]
}
}
}
Module universe_pages
This module provides suggestions of top level categories corresponding to the current result and coming from your site.
Call options
*Note: No member is required, only the presence of the module as an empty object ({}) is sufficient.*
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"universe_pages" : { // Module that provides list of interesting universes pages
}
}
}
Response structure
In response, the universe_pages module will provide an array containing all possible top level categories.
Response
{
"modules" : {
"universe_pages" : {
"parts" : [
{
"product_count": 925,
"image_link": "http://any_cdn_dns/sample_1.jpg",
"level": 1,
"name": "Baby",
"path": "root > Baby",
"universe": "Baby",
"pr": 0,
"score": 2
},
{
"product_count": 157,
"image_link": "http://any_cdn_dns/sample_2.jpg",
"level": 1,
"name": "Men",
"path": "root > Men",
"universe": "Men",
"pr": 0,
"score": 2
}
]
}
}
}
Module scope_pages
This module provides suggestions of categories corresponding to the current result and coming from your site.
Call options
*Note: No member is required, only the presence of the module as an empty object ({}) is sufficient.*
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"scope_pages" : { // Module that provides list of interesting scope pages
}
}
}
Response structure
In response, the scope_pages module will provide an array containing all possible categories.
Response
{
"modules" : {
"scope_pages" : {
"parts" : [
{
"product_count": 92,
"image_link": "http://any_cdn_dns/sample_1.jpg",
"level": 4,
"name": "Sneakers",
"path": "root > Baby > Shoes > Sneakers",
"universe": "Baby",
"pr": 0,
"score": 2
},
{
"product_count": 15,
"image_link": "http://any_cdn_dns/sample_2.jpg",
"level": 4,
"name": "Sneakers",
"path": "root > Men > Shoes > Sneakers",
"universe": "Men",
"pr": 0,
"score": 2
}
]
}
}
}
Module spotlights
This module provides suggestions of possible spotlights according to the search.
Call options
*Note: No member is required, only the presence of the module as an empty object ({}) is sufficient for itself.*
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"spotlights" : { // Module that provides list of available spotlights
}
}
}
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.
{
"modules" : {
"spotlights": {
"matchedParts": [
{
"spotlight_brand_1": { // identifier
"pr": 0,
"score": 2,
"products_count": 1834, // product count
"articles_count": 1834,
"label": "label spotlight brand 1",
"display": {
"logo": "https://brand-logo.png",
"title": "random brand name",
"background": "https://random-background-image.png"
}
}
},
{
"spotlight_brand_2": { // identifier
"pr": 0,
"score": 1,
"products_count": 145, // product count
"articles_count": 145,
"label": "label spotlight brand 2",
"display": {
"logo": "https://brand2-logo.png",
"title": "random brand name",
"background": "https://other-random-background-image.png"
}
}
}
],
"parts" :[] // deprecated
}
}
}
Module acp
This module provides suggestions of terms completion according to the searched terms.
Call options
*Note: No member is required, only the presence of the module as an empty object ({}) is sufficient for itself.*
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"acp" : { // Module that provides list of suggestions
}
}
}
Response structure
In response, the acp module will provide an array with eligible suggestions (4 max.).
Response
{
"modules" : {
"acp": {
"parts" :[
{
"size": 1,
"score": 1,
"key": "sneakers"
},
{
"size": 2,
"score": 2,
"key": "sneakers supersec"
},
{
"size": 2,
"score": 3,
"key": "sneakers red"
}
]
}
}
}
Module references
This module enables search by references according to the searched terms and provides matched items apart from the classical search items.
Call options
| Call options | Description | Type | Default value |
|---|---|---|---|
size | Maximum number of references, for pagination | Positive integer | 5 |
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query": {
"terms": {
"expression": "644"
}
//[...]
}
"modules" : {
"references" : { // Module that provides list of references responding to a search
"size" : 8 // Returns maximum 8 references
}
//[...]
}
}
Response structure
In response, the references module will provide an array with 32 references maximum.
Response
{
"modules" : {
"references" : {
// Array of articles corresponding to the search on references
"parts": [
{
"g:id": "15960",
"g:title": "High blue sneakers"
},
{
"g:id": "15961",
"g:title": "Black sneaker"
}
//[...]
],
// Array of references
"references": [
{
"ref": "64433",
"articles.id": "15960",
"context": "cli_ref"
},
{
"ref": "64434",
"articles.id": "15961",
"context": "cli_ref"
}
//[...]
],
// Total of returned references (equal to the size of "parts")
"total": 5
}
}
}
Module shortcuts
This module allows to retrieve shortcuts to content pages according to the searched terms
Call options
*Note: No member is required, only the presence of the module as an empty object ({}) is sufficient for itself.*
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query": {
"terms": {
"expression": "catalogue"
}
//[...]
}
"modules" : {
"shortcuts" : {}
//[...]
}
}
Response structure
In response, the shortcuts module will provide an array with 32 shortcuts maximum. It will contains 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", "prefered" or "pinned" according to the "promote" module configuration | String |
Shortcut.score | Relevance score | Float |
Shortcut.matchedKeywords | Number of keywords matched by the search terms | Integer |
keywords | List of keywords corresponding to the query | String[] |
Response
{
"modules" : {
"shortcuts" : {
// Array of matching shortcuts
"parts": [
{
"score": 30.251806,
"matched_keywords": 1,
"id": "catalogue",
"label": "Demander un catalogue en ligne",
"url": "https://www.xxx.yy/demande-catalogue",
"promotion": "default"
}
//[...]
],
"keywords": [
"catalogue"
//[...]
]
}
}
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query" : {
"terms": {
"expression" : "snakers"
}
}
//[...]
"modules" : {
//[...]
,
"spell_check" : { }
}
}
Response
{
"modules" : {
//[...]
,
"spell_check" : {
"expression" : "sneakers"
}
}
}
Call not triggering self-correction
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query" : {
"terms": {
"expression" : "sneakers"
}
}
//[...]
"modules" : {
//[...]
,
"spell_check" : { }
}
}
Response
{
"modules" : {
//[...]
,
"spell_check" : {
}
}
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
//[...]
,
"bag" : {
// Custom members
"query_id" : "65e65640-3de6-49e5-9c9c-b270c23551a7"
"timestamp" : "1497538990"
}
}
}
Response
{
"modules" : {
//[...]
,
"bag" : {
// Same members as query
"query_id" : "65e65640-3de6-49e5-9c9c-b270c23551a7"
"timestamp" : "1497538990"
}
}
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
//[...]
,
"statistics" : {}
}
}
Response
{
"modules" : {
//[...]
,
"statistics" : {
// Time taken to process (milliseconds)
"took": 54.603799
}
}
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query":{
//[...]
"user_id" : "edc85853-SAMPLE-ID-329f706a626f",
"track_id" : "00c4a697-SAMPLE-ID-030d69ba96dc"
},
//[...]
"modules" : {
//[...]
,
"tracking" : {
//[...]
}
}
}
Response
{
"modules" : {
//[...]
"tracking" : {
// provided track_id
"track_id" : "00c4a697-SAMPLE-ID-030d69ba96dc",
// Interactive payload for further potential paging purpose
"payload" : "ccb7TztonAlIGthCszq4KRChGKHOOXzfNq+EoZM4cFz3bTkxdRxq3sHX5+4F3V05mEEweueo63sOukPutHQ7TAxoVmZuE75ahJxD1+OppCt3CniRfpO1GKlFUL1PqXNuC6u7r9PK9XEBTxcWf6cNxGBCIfrIQfjXmt1f5rrn0TGS9D4ACONKxMVidLY7DH+ylfeFFMBAwbMA0Z/U6rydWFL7sleObbe3X8eMxL7xBtWDwVYkwRabTK1fgFLmqAA7J0Z8ADs+3CNCck/4L56vRXdBLVDbTGRRwdBz7+YijQUupbWe+ZF5dFqs7IMr9HvR1E85fGbfQdUBNLmQ14dTC8DOYvP/L9Y2ApP+sxgoDFcISl+mj9Gl6qQe+88yduLW/694cF7ZmtdQ7k/t7+birUC1qJbM8iauNbpdUjMIUzY7AfMfvloyYkQQWg1y9aDD2yeTbewibcAoe7YuZ4zTtqqCaLfJ3E/i4JqBc9oguf0pXHh4//YrsDvoyt38ctAo3QryL79rLuFrWOwfOVu9lwcqnbX43cI5zTc4o4cJv5FoiQOmS"
}
}
}
In the example above, we note:
- the return of the only
track_idmember, - the appearance of the
payloadmember, 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_idandtrack_idare mandatory
- For any answer received:
- If no payload is provided: you must destroy any trace of
payloadassociated with thetrack_id(typically in session store). - If a payload is provided to you: you must systematically enter the new
payloadvalue associated with thetrack_id(typically in session store).
- If no payload is provided: you must destroy any trace of
Note: If you have front multiple without sticky-session and a cache system, it must be global to ensure proper tracking.
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
//[...]
"tracking" : {
"payload" : "ccb7TztonAlIGthCszq4KRChGKHOOXzfNq+EoZM4cFz3bTkxdRxq3sHX5+4F3V05mEEweueo63sOukPutHQ7TAxoVmZuE75ahJxD1+OppCt3CniRfpO1GKlFUL1PqXNuC6u7r9PK9XEBTxcWf6cNxGBCIfrIQfjXmt1f5rrn0TGS9D4ACONKxMVidLY7DH+ylfeFFMBAwbMA0Z/U6rydWFL7sleObbe3X8eMxL7xBtWDwVYkwRabTK1fgFLmqAA7J0Z8ADs+3CNCck/4L56vRXdBLVDbTGRRwdBz7+YijQUupbWe+ZF5dFqs7IMr9HvR1E85fGbfQdUBNLmQ14dTC8DOYvP/L9Y2ApP+sxgoDFcISl+mj9Gl6qQe+88yduLW/694cF7ZmtdQ7k/t7+birUC1qJbM8iauNbpdUjMIUzY7AfMfvloyYkQQWg1y9aDD2yeTbewibcAoe7YuZ4zTtqqCaLfJ3E/i4JqBc9oguf0pXHh4//YrsDvoyt38ctAo3QryL79rLuFrWOwfOVu9lwcqnbX43cI5zTc4o4cJv5FoiQOmS"
}
}
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
//[...],
"settings" : {}
}
}
Response
{
"modules" : {
//[...],
"settings" : {
"id" : "65e65640-3de6-49e5-9c9c-b270c23551a8"
}
}
}
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 :
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"showcases" : {
}
}
}
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 :
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"showcases" : {
"type": [
{
"template": "BANNER", //"FULL_PRODUCT" ou "MANUAL_RANKING"
"maxProducts": 5 // Maximum number of products to return
}, ...
//List of showcases and number of products authorized to this showcase type
]
}
}
}
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 1 | all configured attributes |
variants_fields | List of desired attributes for items of a product | Array of strings 2 | all configured attributes |
1 If the field is passed with an empty array as value, no attribute will be returned.
2 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
{
"modules" : {
"showcases": {
{
"showcaseId": "1",
"deduplicated": true,
"size": 5,
"template": "FULL_PRODUCT",
"showcaseConfig": {
"backgroundColor": null,
"text": "texte du showcase",
"textColor": null,
"displayMode": "STACK",
"desktopImgUrl": null,
"mobileImgUrl": null,
},
"parts": [
{
"sf:pr": 0,
"g:id": "e002",
"g:price": 29.99,
"sf:isNew": false,
},
],
"productsCount": 7,
"deduplicatedProductsCount": 5,
},
}
}
}
Contents
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query": {
"terms": {
"expression": "machine"
}
}
//[...]
"modules" : {
"contents_kicker" : {
"size" : 6
}
}
}
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
{
"modules" : {
"contents_kicker" : {
// Array of matching types
"found_types": [
{
"total": 418,// contents count for the following type
"type": "NewsArticle",
"top_hits": [
{
"image_link": "https://www.example.com/content0/bg-single-default.jpg",
"link": "https://www.example.com/blog/entretien-machine-automatique-machine-expresso/",
"description": "Le bon entretien d'une machine à café automatique est primordial pour la faire vivre sur le long terme, et garder une qualité constante.",
"title": "Entretien machine automatique à expresso"
},
// [...]
]
},
{
"total": 153, // contents count for the following type
"type": "Review",
"top_hits": [
{
"image_link": "https://www.example.com/blog/machine-a-cafe-grain.jpg",
"link": "https://www.example.com/blog/machine-a-cafe-grain-test-video/",
"description": "Retrouvez la vidéo test de la nouvelle machine à café",
"title": "Machine à café: test et avis en vidéo"
},
// [...]
]
},
//[...]
],
// Total contents count
"total": 680
}
}
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query": {
"terms": {
"expression": "machine"
}
}
//[...]
"modules" : {
"contents_items" : {
"from": 0
"size" : 32
}
}
}
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
{
"modules" : {
"contents_items" : {
"parts": [
{
"image_link": "https://www.example.com/content0/bg-single-default.jpg",
"link": "https://www.example.com/blog/entretien-machine-automatique-machine-expresso/",
"description": "Le bon entretien d'une machine à café automatique est primordial pour la faire vivre sur le long terme, et garder une qualité constante.",
"title": "Entretien machine automatique à expresso",
"@type": "NewsArticle"
},
// [...]
],related
"total": 205
}
}
}
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.
{
"query": {
"terms": {
"expression": "machine"
}
},
"modules" : {
"contents_items" : {
"from": 0
"size" : 32
}
},
user_actions: {
"apply_content_type": {
"type" : "Review"
}
},
//[...]
}
Example of response
{
"modules" : {
"contents_items" : {
"parts": [
{
"image_link": "https://www.example.com/blog/machine-a-cafe-grain.jpg",
"link": "https://www.example.com/blog/machine-a-cafe-grain-test-video/",
"description": "Retrouvez la vidéo test de la nouvelle machine à café",
"title": "Machine à café: test et avis en vidéo",
"@type": "Review"
},
// [...]
],
"total": 153
}
}
}
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
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"query": {
"terms": {
"expression": "machine"
}
}
//[...]
"modules" : {
"contents_facets" : {
}
}
}
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 associatedscore of importance and count of associated contents | Array of objects |
Response
{
"modules" : {
"contents_facets" : {
"parts": [
{
"facet_name": "NewsArticle.keywords",
"score": 2,
"count": 1554,
"parts": [
{
"value": "Machine à café grain",
"count": 205,
"score": 191
},
{
"value": "Machine expresso",
"count": 167,
"score": 190
}
// [...]
]
},
{
"facet_name": "NewsArticle.audience",
"score": 1,
"count": 5,
"parts": [
{
"value": "Professionnels",
"count": 3,
"score": 0
},
{
"value": "Particuliers",
"count": 2,
"score": 0
}
]
},
// [...]
]
}
}
}
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
{
"query": {
"terms": {
"expression": "machine"
}
},
"modules" : {
"contents_items" : {
"from": 0
"size" : 32
}
},
"user_actions": {
"apply_content_filters": {
"NewsArticle.audience" : ["Professionnals"]
}
},
//[...]
}
Example of response
{
"modules" : {
"contents_items" : {
"parts": [
{
"image_link": "https://www.example.com/content-pro-0/bg-single-default.jpg",
"link": "https://www.example.com/blog/entretien-machine-automatique-machine-expresso-professionnelle/",
"description": "Le bon entretien d'une machine à café automatique est primordial pour la faire vivre sur le long terme, dans un usage intensif",
"title": "Entretien machine automatique à expresso professionnelle",
"@type": "NewsArticle"
},
[...]
],
"total": 3
}
}
}
- In case of use of the
contents_facetsmodule, if we apply a filter on a facet, the values returned in this facet are those of the requestedexpressionapplying all other filters except this one.
So this user can still reopen his result.
{
"query": {
"terms": {
"expression": "machine"
}
},
"modules" : {
"contents_facets" : {
}
},
user_actions: {
"apply_content_filters": {
"NewsArticle.audience" : ["Professionnals"]
}
},
//[...]
}
Example of response
{
"modules" : {
"contents_facets" : {
"parts": [
{
"facet_name": "NewsArticle.keywords",
"score": 2,
"count": 651,
"parts": [
{
"value": "Machine à café grain",
"count": 75,
"score": 54
},
{
"value": "Machine expresso",
"count": 42,
"score": 53
}
// [...]
]
},
{
"facet_name": "NewsArticle.audience",
"score": 1,
"count": 5,
"parts": [
{
"value": "Professionnals",
"count": 3,
"score": 0
},
{
"value": "Individuals",
"count": 2,
"score": 0
}
]
},
// [...]
]
}
}
}
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 1 | all configured attributes |
suggested_products.variants_fields | List of desired attributes for items of a product | Array of strings 2 | all configured attributes |
Provided keywords are sorted by relevance.
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/suggested_keywords
{
//[...]
"modules" : {
"suggested_keywords" : { // Module that provides list of interesting keywords
"size": 4,
"suggested_products": { // Module that provides list of interesting products for each keyword
"size": 4,
"fields": ["g:id","g:link", "g:title"]
}
}
}
}
Response structure
In response, the suggested_keywords module will contain an array of suggested keywords and, if asked, products.
Response
{
"modules" : {
"suggested_keywords" : {
"parts" : [
{
"keywords": "baskets",
"score": 2,
"suggested_products": {
"parts":[
{
//[...]
"g:id": "502598_0480",
"g:link": "https://example.com/products/402598_0480",
//[...]
"g:title": "fantastic basket",
//[...]
"sf:pr": 0
},
//[...]
]
}
},
{
"keywords": "sneakers",
"score": 1,
"suggested_products": {
"parts":[
{
//[...]
"g:id": "494351_2230",
"g:link": "https://example.com/products/494351_2230",
//[...]
"g:title": "Black sneaker",
//[...]
"sf:pr": 0
},
//[...]
]
}
}
]
}
}
}
Module suggested_scope_pages
This module provides a list of categories suggestions related to result from suggested_keywords.
Call options
| Call options | Description | Type | Default value |
|---|---|---|---|
size | Maximum number of scopes | Positive integer | 4 |
Provided scopes are sorted by relevance.
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"suggested_scope_pages" : { // Module that provides list of interesting scope pages
"size": 4
}
}
}
Response structure
In response, the suggested_scope_pages module will provide an array of categories.
Response
{
"modules" : {
"suggested_scope_pages" : {
"parts" : [
{
"product_count": 92,
"image_link": "http://any_cdn_dns/sample_1.jpg",
"level": 4,
"name": "Sneakers",
"path": "root > Baby > Shoes > Sneakers",
"universe": "Baby",
"pr": 0,
"score": 2
},
{
"product_count": 15,
"image_link": "http://any_cdn_dns/sample_2.jpg",
"level": 4,
"name": "Sneakers",
"path": "root > Men > Shoes > Sneakers",
"universe": "Men",
"pr": 0,
"score": 2
}
]
}
}
}
Module suggested_spotlights
This module provides a list of spotlights suggestions related to result from suggested_keywords.
Call options
| Call options | Description | Type | Default value |
|---|---|---|---|
size | Maximum number of spotlights | Positive integer | 4 |
Provided spotlights are sorted by relevance.
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
//[...]
"modules" : {
"suggested_spotlights" : { // Module that provides list of suggested spotlights
"size": 4
}
}
}
Response structure
In response, the suggested_spotlights module will provide an array with suggested spotlights.
Response
{
"modules" : {
"suggested_spotlights": {
"parts" :[
{
"spotlight_brand_1": { // identifier
"pr": 0,
"score": 2,
"product_count": 1834 // product count
}
},
{
"spotlight_brand_2": { // identifier
"pr": 0,
"score": 1,
"product_count": 145 // product count
}
}
]
}
}
}
Module suggested_shortcuts
This module allows to retrieve a list shortcuts suggestions related to result from suggested_keywords.
Call options
| Call options | Description | Type | Default value |
|---|---|---|---|
size | Maximum number of shortcuts | Positive integer | 4 |
Provided shortcuts are sorted by relevance.
Call
POST https://api.sensefuel.live/discovery/96cd2378-sample-1-b92af0700c54/search
{
"modules" : {
"suggested_shortcuts" : { // Module that provides list of suggested shortcuts
"size": 4
}
}
}
Response structure
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
{
"modules" : {
"suggested_shortcuts" : {
// Array of matching shortcuts
"parts": [
{
"score": 30.251806,
"matched_keywords": 1,
"id": "catalogue",
"label": "Demander un catalogue en ligne",
"url": "https://www.xxx.yy/demande-catalogue",
"promotion": "default"
}
//[...]
],
"keywords": [
"catalogue"
//[...]
]
}
}
}
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 thesettingsmodule). If it changes, you have to call thesettingsaction.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 queriesranking: a list of available attributes in thesortmodulespotlights: the spotlight configuration allowing you to interpret the results of thespotlightsandsuggested_spotlightsmodulesshortcuts: the shortcut configuration allowing you to interpret the results of theshortcutsandsuggested_shortcutsmodulesshowcases: 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:
stringlongdouble
When reading the catalog feed, the types are inferred based on the first documents read and bearing these attributes (in alphabetical order on theg:idfield)
Example
{
"id": "a83dbe545c0b4240a0beaf355f0f088f",
"settings": {
"fields": [
{
"field": "g:id",
"type": "string",
"labels": {
"single": "article id",
"multiple": "article ids"
},
"filterable": false,
"search_attributes": false
},
{
"field": "g:availability",
"type": "string",
"labels": {
"single": "article availability",
"multiple": "article availabilities"
},
"filterable": false,
"search_attributes": false
},
{
"field": "sf:scope_id",
"type": "string",
"labels": {
"single": "scope_id",
"multiple": "scope_ids"
},
"filterable": false,
"search_attributes": true
},
{
"field": "c:price_numerical",
"type": "double",
"labels": {
"single": "price",
"multiple": "prices"
},
"filterable": true,
"search_attributes": true
},
{
"field": "c:price_category",
"type": "long",
"labels": {
"single": "price category",
"multiple": "price categories"
},
"filterable": true,
"search_attributes": true
}
],
[...]
}
}
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
{
"id": "a83dbe545c0b4240a0beaf355f0f088f",
"settings": {
"ranking": [
{
"field": "sf:isDiscount",
"display": "Discount",
"order": "desc"
},
{
"field": "sf:isNew",
"display": "News",
"order": "desc"
},
{
"field": "sf:price",
"display": "Price descending",
"order": "desc"
},
{
"field": "sf:price",
"display": "Price ascending",
"order": "asc"
}
],
// [...]
}
}
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
{
"id": "a83dbe545c0b4240a0beaf355f0f088f",
"settings": {
"spotlights": [
"spotlight_brand_1": {
"display": {
"logo": "https://www.example.com/visuels/logo_brand_1.svg",
"title": "Brand 1",
"background": "https://www.example.com/images/logo_brand_1_background.png",
"background_color": "#BF1111",
"background_position": "center center",
"alternative_background_image": "https://alt.example.com/images/logo_brand_1_background.png",
"alternative_background_position": "center right"
},
"label": "Brand 1",
"promotion": "pinned",
"products_count": 35,
"articles_count": 37
},
"spotlight_event_1": {
"display": {
"logo": null,
"title": "New collection",
"background": "https://www.example.com/images/logo_event_1_background.png",
"description": "Discover our new collection !",
"background_color": "#D66D6D",
"background_position": "center center",
"alternative_background_image": "https://alt.example.com/images/logo_event_1_background.png",
"alternative_background_position": "top center"
},
"label": "Collection",
"products_count": 22,
"articles_count": 26
}
],
// [...]
}
}
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"]
}
}