Introduction to the 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.

Response values

Specification of the values returned in the response:
Field name
Type
Description
product_results
int
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
int
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 to the image.
result[].url
String
The URL of the product.
result[].price
int
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
int
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
int
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
int
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
int
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
int
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
int
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
int
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
int
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
int
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
int
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
int
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.