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 in 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 parameter filters[], 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 parameter “product_count”

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 depends 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 matches 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 parameter “category_count”

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 parameter “blog_post_count”

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 parameter “site_page_count”

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 parameter “brand_count”

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