Introduction to Search API

We recommend using the JavaScript SDK to perform the searches. One case where you might want to use the REST-API is if you have context-aware pricing, where the logic resides in your system. In that case, you might want to do the search whereafter you look the products up in your system to enrich with the right prices.

Search configuration key

You can find the search configuration key, by going to the search configuration on the dashboard, as shown below.

Filters

The filter parameter consists of the format &filters[]={key}:{value}. If you want to filter by the brand Nike, you would use &filters[]=brand:nike. For each value, you need to add the filters[] parameter, which means that if you want to filter by both color and brand you would add &filters[]=color:blue&filters[]=brand:nike.

For range filters the format is &filters[]={key}:{value from},{value to}. As an example, if you want to filter products in the price range 20 to 100 the query parameter would look like &filters[]=price:20,100.

Note: If you filter on custom product fields, then you need to index the fields. This can be done from Data Setup > Product Fields, and then tick of the Indexed checkbox. The indexing can take a little while, and you can always check the status at the top of the page.

AI Synonyms

The response will contain information about wether or not AI-synonyms were used to find the product results. At the top level there will be a suggestedProductStatus field that can have three values. Indicating how the products in the result was found. The values are:

NO_SUGGESTED: None of the products in the result were found using AI-synonyms. MIXED: The products are a mix where some were found using AI-synonyms and some were not. ONLY_SUGGESTED: All of the products in the result were found using AI-synonyms.

This field could potentially be used to decide what headline to show over the search results.

Each individual product in the result also has a boolean field called suggestedResult. This field is trueif the product was found using AI-synonyms and false if not. This field can be useful if you want to render the product differently in the UI if it was found using the AI-synonyms.

Response values

Specification of the values returned in the response:

Field name	Type	Description
product_details	Integer	The number of results found in total. The result array below only contains the number of results, specified in the input product_count parameter.
start	Integer	Shows the starting position, as stated in the start input parameter.
result	Array	An array of product search results.
result[].title	String	The title of the product.
result[].imageUrl	String	The URL of the image.
result[].url	String	The URL of the product.
result[].price	Integer	The price of the product.
result[].priceFormatted	String	The price formatted as a String, using formatting rules applied by Hello Retail - Please contact Hello Retail support, if you need other formatting options.
result[].oldPrice	Integer	The price of the product, as it was before a price change.
result[].oldPriceFormatted	String	The price of the product, as it was before a price change, formatted by using the formatting rules applied by Hello Retail.
result[].isOnSale	Boolean	Indicates whether the product is on sale or not.
result[].description	String	The description of the product.
result[].currency	String	The currency for the configured webshop.
result[].inStock	Boolean	Indication whether the product is instock or not.
result[].extraData.?	-	This might hold data, used for other purposes, like filtering and rendering. The results depend on the configuration of the webshop.
filters	Map	Each entry represents a filterable property on the products. The keys are the name of the property, and the value is a list of options.
filters.?[].title	String	The value that the results can be limited to. Usually, human-readable, except for hierarchies-filters. (See below)
filters.?[].count	Integer	How many results match this filter.
filters.?[].query	String	The string that should be send in a filters[] parameter, to limit the search to these results.
filters.?[].selected	Boolean	Whether this filter was used to limit the current results or not.
filters.hierarchies[].title	String	For hierarchies, the title is delimited with $, where each part represents a level of the hierarchy. For example, “Plumbing$Sinks$” specifies the category “Sinks”, which is a subcategory of “Plumbing”.
filters.hierarchies[].level	Integer	How deep this hierarchy (equals to the number of parts in the title).
filters.price.min	String	The lowest price within the products of the current search, if the price filter was not applied.
filters.price.max	String	The highest price withing the products of the current search, if the price filter was not applied.
filters.price.selectedMin	String	The currently selected minimum price.
filters.price.selectedMax	String	The currently selected maximum price.
category_results	Integer	The number of category results found in total. The categories array below only contains the number of results specified in the category_count parameter.
category_start	Integer	The starting position of the category results.
categories[].title	String	Title of the category.
categories[].url	String	URL of the category.
categories[].imgUrl	String	Image URL of the category.
categories[].description	String	Description of the category.
blog_post_results	Integer	The number of blog post results found in total. The blog_posts array below only contains the number of results specified in the blog_post_count parameter.
blog_post_start	Inetger	The starting position of the blog post results.
blog_posts[].title	String	Title of the blog post.
blog_posts[].url	String	URL of the blog post.
blog_posts[].imgUrl	String	Image URL of the blog post.
blog_posts[].description	String	Description of the blog post.
site_page_results	Integer	The number of site page results found in total. The site pages array below only contains the number of results specified in the site_page_count parameter.
site_page_start	Integer	The starting position of the site page results.
site_pages[].title	String	Title of the site page.
site_pages[].url	String	URL of the site page.
site_pages[].imgUrl	String	Image URL of the site page.
site_pages[].description	String	Description of the site page.
brand_results	Integer	The number of brand results found in total. The categories array below only contains the number of results specified in the brand_count parameter.
brand_start	Integer	The starting position of the brand results.
brands[].title	String	Title of the brand.
brands[].url	String	URL of the brand.
brands[].imgUrl	String	Image URL of the brand.
brands[].description	String	Description of the brand.