Techdocs
Search
K
Links
Comment on page

Search

Searching

It is possible to call the Search API directly from the JS library to fetch search results directly on frontend.
For the most basic search the fields parameter should be provided to specify what product/keyword fields should be returned. Both products and keywords can be used separately and together, depending on the use case. For all parameters, see the reference.
nostojs(api => {
api.search({
query: 'my search',
products: { fields: ["name"] },
keywords: { fields: ["keyword"] }
}).then(response => {
console.log(response);
});
});
The api.search function also accepts the following options:
Option
Default
Description
redirect
false
Automatically redirect if search returns a redirect
track
null
Track search query by provided type
The function automatically loads session parameters required for personalization & segments in the background.

Search page

For a search page in most cases the facets parameter should be provided.
Also redirect & track should be enabled to automatically track searches to Nosto analytics & redirect if API returns a redirect request.
nostojs(api => {
api.search({
query: 'my search',
products: {
facets: ['*'],
fields: ['name'],
size: 10
}
}, {
redirect: true,
track: 'serp'
}).then(response => {
console.log(response);
});
});

Autocomplete

track should be enabled to automatically track searches to Nosto analytics.
nostojs(api => {
api.search({
query: 'my search',
products: {
fields: ['name'],
size: 10
},
keywords: {
fields: ['keyword'],
size: 5
}
}, {
track: 'autocomplete'
}).then(response => {
console.log(response);
});
});

Category page

For category pages in most cases the facets parameter should be provided. And either categoryId or categoryPath should be also provided.
Furthermore redirect & track should be enabled to automatically track searches to Nosto analytics & redirect if API returns a redirect request.
nostojs(api => {
api.search({
products: {
categoryId: '12345',
fields: ['name'],
size: 10
}
}, {
track: 'category',
redirect: true
}).then(response => {
console.log(response);
});
});

Session parameters

For some of the search features to work properly, such as personalised results and segments, the search function needs to be able to access information about the user's session from the front-end.
The search function of the JS API already includes session state automatically.
To get all session data the following snippet can be used:
nostojs(api => {
api.getSearchSessionParams(options).then(response => {
console.log(response);
});
});
The results of this function should be passed to search query sessionParams parameter. In case search is called from backend, it should pass this data to backend (e.g. using form data).
The function accepts the following options:
Option
Default
Description
maxWait
2000
Maximum execution time in MS
cacheRefreshInterval
60000
Maximum cache time

Analytics

Tracking search events to analytics can be divided into three parts: search, search submit, search product/keyword click. These are user behaviours that should be tracked:
  • search submit (type = serp)
  • faceting, paginating, sorting (type = serp/category)
  • autocomplete input (type = autocomplete)
  • search results product click (type = serp/autocomplete/category)
  • autocomplete keyword click (type = autocomplete)
  • category merchandising results (type = category)
JS API library provides tracking helpers for all of these cases.
User actions that lead to search results should be tracked with api.recordSearch() after search request is done:
  • search submit (type = serp) - user submits search query in autocomplete component and is landed to SERP
  • faceting, paginating, sorting (type = serp/category) - user adjusts current search results by filtering (e.g. brand), selecting search page, sorting results
  • autocomplete input (type = autocomplete) - user sees partial results while typing in search input
  • category merchandising results (type = category) - user sees specific category results when category is selected (category merchandising must be implemented)
You don't need to execute api.recordSearch()if you call api.search(query, { track: 'serp'|'autocomplete'|'category'}) function from JS API, becauseapi.search()already calls api.recordSearch() when track option is provided.
nostojs(api => {
api.recordSearch(
type,
query,
response
)
})
Parameter
Description
type
Search type: serp, autocomplete, category
query
Partial search API query containing: query, products.sort, products.filter
response
Partial search API response containing: products.hits.productId[], products.fuzzy, products.total, products.size, products.from
Example:
api.recordSearch(
"serp",
{
query: "shoes",
products: {
sort: [{ field: "price", order: "asc" }],
filter: [{ "field": "brand", "value": "Nike" }]
}
},
{
products: {
hits: [{ productId: "123" }, { productId: "124" }],
fuzzy: true,
total: 2,
size: 2,
from: 0
}
}
)

Search form submit

Search queries are categorised into two groups: organic and non-organic searches. In order to mark a search query as an organic search you need to call api.recordSearchSubmit(). You should call it on search input submit only, before search request is sent.
nostojs(api => {
api.recordSearchSubmit(query)
})
Organic search - is a search query submitted through search input and which lead to SERP (search engine results page). Following faceting, paginating, sorting queries on organic query is also counted as organic.

Search product/keyword click

Product clicks should be tracked in autocomplete component, SERP, category page with api.recordSearchClick() by providing component (type), where click occurred, and clicked product data:
nostojs(api => {
api.recordSearchClick(type, hit)
})
Parameter
Text
type
Search type: serp, autocomplete, category
hit
Object containing productId and url, collected from clicked product
Example:
api.recordSearchClick(
"autocomplete",
{ productId: "123", url: "https://myshop.com/product123" }
)
Product and keyword clicks must be tracked separately by binding to two separate click events.
Keyword clicks should be tracked in autocomplete component with api.recordSearchClick() by providing type = autocomplete and keyword hit object:
nostojs(api => {
api.recordSearchClick(
'autocomplete',
{ keyword: 'green' }
)
})