Search using the REST-API¶
The REST API can be used to do searches. You can either get the results as JSON or rendered as HTML. You can search in one or more types of content. You will often want to search in the product catalog, but you can also search other content types you indexed into Hello Retail.
Request¶
The endpoint is available at https://core.helloretail.com/serve/search.
You use it by sending a HTTP POST request with a JSON body. The content type must be application/json or text/plain 1. There are some general settings at the top level, and then for each content type you want to search you must provide an object with settings for that content type.
Example of a request that searches the product catalog and the categories content:
{
"query": "running",
"key": "{search config key}",
"products": {
"returnFilters": true,
"start":0,
"count":10,
"fields":["title","price", "url", "extraData.size", "extraDataNumber.rating"],
"filters": ["brand:Nike"],
"sorting": ["price desc"]
},
"categories": {
"start":0,
"count":5,
"fields":["title", "url"],
"sorting":["title asc"]
},
"redirects": {
"start": 0,
"count": 1
},
"format": "json"
}
Multi-language Examples¶
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d '{
"query": "running",
"key": "{search config key}",
"products": {
"returnFilters": true,
"start": 0,
"count": 10,
"fields": ["title", "price", "url", "extraData.size", "extraDataNumber.rating"],
"filters": ["brand:Nike"],
"sorting": ["price desc"]
},
"categories": {
"start": 0,
"count": 5,
"fields": ["title", "url"],
"sorting": ["title asc"]
},
"redirects": {
"start": 0,
"count": 1
},
"format": "json"
}' \
https://core.helloretail.com/serve/search
import requests
api_url = "https://core.helloretail.com/serve/search"
api_key = "<YOUR_API_KEY>"
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}"
}
payload = {
"query": "running",
"key": "{search config key}",
"products": {
"returnFilters": True,
"start": 0,
"count": 10,
"fields": ["title", "price", "url", "extraData.size", "extraDataNumber.rating"],
"filters": ["brand:Nike"],
"sorting": ["price desc"]
},
"categories": {
"start": 0,
"count": 5,
"fields": ["title", "url"],
"sorting": ["title asc"]
},
"redirects": {
"start": 0,
"count": 1
},
"format": "json"
}
response = requests.post(api_url, headers=headers, json=payload)
print(response.json())
<?php
$apiUrl = 'https://core.helloretail.com/serve/search';
$apiKey = '<YOUR_API_KEY>';
$data = [
"query" => "running",
"key" => "{search config key}",
"products" => [
"returnFilters" => true,
"start" => 0,
"count" => 10,
"fields" => ["title", "price", "url", "extraData.size", "extraDataNumber.rating"],
"filters" => ["brand:Nike"],
"sorting" => ["price desc"]
],
"categories" => [
"start" => 0,
"count" => 5,
"fields" => ["title", "url"],
"sorting" => ["title asc"]
],
"redirects" => [
"start" => 0,
"count" => 1
],
"format" => "json"
];
$options = [
'http' => [
'header' => [
"Content-Type: application/json",
"Authorization: Bearer $apiKey"
],
'method' => 'POST',
'content' => json_encode($data),
],
];
$context = stream_context_create($options);
$result = file_get_contents($apiUrl, false, $context);
if ($result === FALSE) { /* Handle error */ }
echo $result;
?>
require 'net/http'
require 'uri'
require 'json'
api_url = URI.parse('https://core.helloretail.com/serve/search')
api_key = '<YOUR_API_KEY>'
headers = {
'Content-Type' => 'application/json',
'Authorization' => "Bearer #{api_key}"
}
payload = {
query: 'running',
key: '{search config key}',
products: {
returnFilters: true,
start: 0,
count: 10,
fields: ['title', 'price', 'url', 'extraData.size', 'extraDataNumber.rating'],
filters: ['brand:Nike'],
sorting: ['price desc']
},
categories: {
start: 0,
count: 5,
fields: ['title', 'url'],
sorting: ['title asc']
},
redirects: {
start: 0,
count: 1
},
format: 'json'
}
http = Net::HTTP.new(api_url.host, api_url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(api_url.request_uri, headers)
request.body = payload.to_json
response = http.request(request)
puts response.body
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
public class HelloRetailSearchApiExample {
public static void main(String[] args) throws Exception {
String apiUrl = "https://core.helloretail.com/serve/search";
String apiKey = "<YOUR_API_KEY>";
String jsonInputString = """
{\n \"query\": \"running\",\n \"key\": \"{search config key}\",\n \"products\": {\n \"returnFilters\": true,\n \"start\": 0,\n \"count\": 10,\n \"fields\": [\"title\", \"price\", \"url\", \"extraData.size\", \"extraDataNumber.rating\"],\n \"filters\": [\"brand:Nike\"],\n \"sorting\": [\"price desc\"]\n },\n \"categories\": {\n \"start\": 0,\n \"count\": 5,\n \"fields\": [\"title\", \"url\"],\n \"sorting\": [\"title asc\"]\n },\n \"redirects\": {\n \"start\": 0,\n \"count\": 1\n },\n \"format\": \"json\"\n}""";
URL url = new URL(apiUrl);
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Authorization", "Bearer " + apiKey);
con.setDoOutput(true);
try(OutputStream os = con.getOutputStream()) {
byte[] input = jsonInputString.getBytes("utf-8");
os.write(input, 0, input.length);
}
int code = con.getResponseCode();
System.out.println(code);
// Read response as needed
}
}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var apiUrl = "https://core.helloretail.com/serve/search";
var apiKey = "<YOUR_API_KEY>";
var json = @"{
\"query\": \"running\",
\"key\": \"{search config key}\",
\"products\": {
\"returnFilters\": true,
\"start\": 0,
\"count\": 10,
\"fields\": [\"title\", \"price\", \"url\", \"extraData.size\", \"extraDataNumber.rating\"],
\"filters\": [\"brand:Nike\"],
\"sorting\": [\"price desc\"]
},
\"categories\": {
\"start\": 0,
\"count\": 5,
\"fields\": [\"title\", \"url\"],
\"sorting\": [\"title asc\"]
},
\"redirects\": {
\"start\": 0,
\"count\": 1
},
\"format\": \"json\"
}";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(apiUrl, content);
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);
}
}
Available top level properties:
| Name | Type | Description |
|---|---|---|
| query | String (Required) | The search query to send to the requested indexes. A single * can be used to do a wildcard search. |
| key | String (Required) | Key of the configuration you want to use when searching. You get this from the search configuration page on My Hello Retail. |
| id | Integer | ID of a version of a search configuration. Only needed if you want to fetch the Draft version of a search configuration. |
| trackingUserId | String | Hello Retail ID of the user visiting your site. This is used to apply personalization and for tracking purposes. You can get this ID server side by getting the value of the cookie named hello_retail_id. |
| products | Object | used to specify the settings for searching the product catalog. See more below |
| categories | Object | used to specify the settings for searching categories content. See more below |
| brands | Object | used to specify the settings for searching brand content. See more below |
| sitePages | Object | used to specify the settings for searching site page content. See more below |
| blogPosts | Object | used to specify the settings for searching blog post content. See more below |
| redirects | Object | used to specify the settings for searching redirects. See more below |
| format | String | Specifies the format in which the API will return the results. html and json are accepted values, default value is json.. The html format should normally not be used directly, but only be used by the managed solution |
| deviceType | Enum | Specifies the device type the results will be shown on and is used to select settings that are device specific. Valid values are DESKTOP and MOBILE. |
The products setting¶
This setting is used to configure how the product catalog is searched. It could look something like this:
{
"start":0,
"count":10,
"fields":["title","price", "url", "extraData.size", "extraDataNumber.rating"],
"filters": ["brand:Nike"],
"sorting": ["price desc"],
"returnFilters": true,
"excludeSiblingFilters": [],
"returnInitialContent": true
}
Available properties
| Name | Type | Description |
|---|---|---|
| start | Number | The starting point when returning results. Used for pagination. Default value is 0 |
| count | Number (required) | The number of results to return |
| fields | List of strings | Names of the fields to return for each product when using JSON response format. The default is to return all fields. There are performance benefits of only requesting the fields that are actually needed |
| filters | List of strings | Limit returned products to those matching the specified filters. To filter by a field you have to make sure the field is indexed. Indexed fields are managed from the "Data Fields" settings in My hello Retail |
| sorting | List of strings | Sort the order of the product results by specifying an array of sorting strings. The sorting strings are build up by a structure of "{field name} {sorting order}" where field name can i.e. be "inStock" and sort order can be either "asc" for ascending or "desc" for descending order. You can sort by any indexed field. Indexed fields are managed from the "Data Fields" settings in My hello Retail |
| returnFilters | Boolean | Determines if the list of available filters (also known as facets) should be returned. The filters enabled in the search configuration determine what fields are considered when returning this list. The list is also affected by the current query and the currently applied filters. Returning the available filters comes with a performance hit. Only request them when actually needed, for instance when fetching the first page of results to build a filtering UI. |
| excludeSiblingFilters" | List of strings | This can be used when returnFilters is true. It modifies what filters are returned for the specified fields. The normal behaviour for each field is to return filters as if any filters on the current field are not applied. This setting changes that so that only filters that are available in the current result set are returned. \Example - where value is set to brand: Consider the situation where you have two products: - "Running Shoe" with brand "Nike" - "Tennis Shoes" with brand: "Adidas" If you search for "shoes" and add a brand filter to only get "Nike" products. The search engine would only return the "Running Shoe" product. If you set returnFilters=true it would return a list of two available brand filters; The "Nike" filter that is currently selected and the "Adidas" filter that is not active. That information is typically needed to be able to build a UI where you can add filters without all filter options disappearing once you start selecting filters. If you add "brand" to excludeSiblingFilters, the "Adidas" filter will not be returned in the above example. It will only return the filter values that are available in the current filter set. The default value is the empty list |
| returnInitialContent | Boolean | Determines if initial content configured in My Hello Retail should be returned. Note that any configured initial content will always be returned in the case of zero results found in the product catalog. The default value is false |
The categories, brands, blogPosts and sitePages settings¶
These settings are used to configure how those four content catalogs are searched. It could look something like this:
{
"start":0,
"count":10,
"fields":["title","price", "url", "extraData.size", "extraDataNumber.rating"],
"filters": ["brand:Nike"],
"sorting": ["price desc"]
}
These are very similar to searching the product catalog, but without some of the features
Available properties
| Name | Type | Description |
|---|---|---|
| start | Number | The starting point when returning results. Used for pagination. Default value is 0 |
| count | Number (required) | The number of results to return |
| fields | List of strings | Names of the fields to return for each content item when using JSON response format. The default is to return all fields. There are performance benefits of only requesting the fields that are actually needed |
| filters | List of strings | Limit returned content items to those matching the specified filters. To filter by a field you have to make sure the field is indexed. Indexed fields are managed from the "Data Fields" settings in My hello Retail |
| sorting | List of strings | Sort the order of the content results by specifying an array of sorting strings. The sorting strings are build up by a structure of "{field name} {sorting order}" where field name can i.e. be "inStock" and sort order can be either "asc" for ascending or "desc" for descending order. You can sort by any indexed field. Indexed fields are managed from the "Data Fields" settings in My hello Retail |
The redirects settings¶
These settings are used to configure how many redirects to return. It could look something like this:
Redirects are configured on My Hello Retail. You would rarely need to return many redirects, or paginate through the result, but the start property is provided for consistency with the other types.
Available properties
| Name | Type | Description |
|---|---|---|
| start | Number | The starting point when returning results. Used for pagination. Default value is 0 |
| count | Number (required) | The number of results to return |
Response¶
The response will be a JSON document. The content will depend on the requested format.
Example of a response with JSON formmatted results:
{
"success": true,
"query": "cap",
"products": {
"start": 0,
"requestedCount": 2,
"returnedCount": 2,
"totalCount": 12,
"results": [
{
"title": "Blue Cap",
"extraData": {
"color": "Blue"
},
"extraDataList": {
"sizes": ["XL", "L", "M"]
},
"price": 100,
"url": "https://shop.example.com/blue-cap",
"suggestedResult": false
},
{
"title": "Red Cap",
"extraData": {
"color": "Red"
},
"extraDataList": {
"sizes": ["L", "M", "S"]
},
"price": 200,
"url": "https://shop.example.com/red-cap",
"suggestedResult": false
}
],
"filters": [
{
"name": "hierarchies",
"settings": {
"name": "hierarchies",
"type": "LIST",
"title": "Categories"
},
"values": [
{
"title": "Hats$",
"count": 12,
"query": "hierarchies:Hats$",
"selected": true
},
{
"title": "Shirts$",
"count": 12,
"query": "hierarchies:Shirts$",
"selected": true
}
]
},
{
"name": "isOnSale",
"settings": {
"name": "isOnSale",
"type": "BOOLEAN",
"title": "On Sale",
"filteringText": "Yes",
"negatedFilteringText": "No"
},
"values": [
{
"title": "No",
"count": 8,
"query": "isOnSale:false",
"selected": false
},
{
"title": "Yes",
"count": 4,
"query": "isOnSale:true",
"selected": false
}
]
},
{
"name": "price",
"settings": {
"name": "price",
"type": "RANGE",
"title": "Pris"
},
"min": "16.0",
"max": "90.0",
"selectedMin": "10",
"selectedMax": "300"
},
],
"sorting": [
{
"name": "inStock",
"settings": {
"name": "inStock",
"title": "Sort by stock status",
"ascendingText": "In stock first",
"descendingText": "Out of stock first"
},
"descending": {
"query": "inStock desc",
"selected": false
},
"ascending": {
"query": "inStock asc",
"selected": false
}
},
{
"name": "price",
"settings": {
"name": "price",
"title": "Sort by price",
"ascendingText": "Cheapest first",
"descendingText": "Most expensive first"
},
"descending": {
"query": "price desc",
"selected": true
},
"ascending": {
"query": "price asc",
"selected": true
}
}
],
"suggestedProductStatus": "MIXED"
},
"categories": {
"start": 0,
"requestedCount": 4,
"returnedCount": 2,
"totalCount": 2,
"results": [
{
"title": "Accessories",
"url": "https://shop.example.com/category/accessories",
"extraData": {
"type": "misc"
}
},
{
"title": "Clothing",
"url": "https://shop.example.com/category/clothing",
"extraData": {
"type": "fashion"
}
}
]
},
"redirects": {
"start": 0,
"requestedCount": 1,
"returnedCount": 1,
"totalCount": 3,
"results": [
{
"title": "Opening hours",
"url": "https://shop.example.com/opening-hours#aw_source=ps-12345678-aaaa-bbbb-cccc-1b6bdd6a7d31|rd-1|running|",
"trackingCode": "ps-12345678-aaaa-bbbb-cccc-1b6bdd6a7d31|rd-1|running|",
"originalUrl": "https://shop.example.com/opening-hours"
}
]
},
}
Available root level properties in the response
| Name | Type | Description |
|---|---|---|
| success | Boolean | Indicating if the search succeeded or failed |
| query | String | The query that this is a response to |
| products | Object | Contains information about the returned products and the products them selves if the format is json. See more below |
| categories | Object | Contains information about the returned products and the products them selves if the format is json. See more below |
| brands | Object | Contains information about the returned products and the products them selves if the format is json. See more below |
| sitePages | Object | Contains information about the returned products and the products them selves if the format is json. See more below |
| blogPosts | Object | Contains information about the returned products and the products them selves if the format is json. See more below |
| html | String | If the format is html this will contain the rendered search result |
The products response¶
The products response contains the matching products, and if requested the available sorting and filtering options (facets)
The available properties in the products response are:
| Name | Type | Description |
|---|---|---|
| start | Number | The starting point of these results. Usefull for pagination |
| requestedCount | Number | The number of items requested in the search request |
| returnedCount | Number | The number of returned items. Might be lower than the requested count if fewer items than the requested count match the query |
| totalCount | Number | The total number or items matching the query |
| results | Product[] | The products matching the search query. Each item will contain the fields requested in the fields parameter. If no fields parameter is added it will contain all fields. If the format is html then this property will not exist. The available fields on these objects are described in the sdk introduction. |
| filters | List of objects | If returnFilters was true in the search request this list will contain the available filter options, also known as facets. This response will typically be used to build a filtering UI for the end user. There are three types of filters. BOOLEAN where there are two possible filter values, LIST where there is a list of possible filter values. For each of those the filter object will contain a list of available options, the number of products matching each option, and a query that can be used in the filters field in the search request to apply this filter. The third type of filter is RANGE. This filter has a minimum and a maximum value, and if the filter is active it will also contain a selected minimum and a selected maximum. To add a range filter to the search request the format is "{field name}:{minimum value},{maximum value}". Both ends of the range are inclusive. The data also contains strings, like titles, that can be used when building a filtering UI. These strings can be configured in My Hello Retail |
| sorting | List of objects | The available sorting options that can be passed to the sorting attribute in the request. For each sorting option a query for each sorting direction is provided. It also contains strings that can be used when building a sorting UI. These strings can be configured in My Hello Retail |
| suggestedProductStatus | String | Provides information about how AI synonyms was used when generating this search result. See more below |
Notes about AI Synonyms¶
The the product response will contain information about wether or not AI-synonyms were used to find the product results. At the product response 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.
The categories, brands, blogPosts and sitePages responses¶
If the type was requested the response will contain an object for the type. The object has the same structure for all types. The available properties are:
| Name | Type | Description |
|---|---|---|
| start | Number | The starting point of these results. Usefull for pagination |
| requestedCount | Number | The number of items requested in the search request |
| returnedCount | Number | The number of returned items. Might be lower than the requested count if fewer items than the requested count match the query |
| totalCount | Number | The total number or items matching the query |
| results | Object | The items matching the search query. Each item will contain the fields requested in the fields parameter. If no fields parameter is added it will contain all fields. If the format is html then this property will not exist. |
The redirects responses¶
If the redirects were requested the response will contain an object for it. The available properties on the response redirects are:
| Name | Type | Description |
|---|---|---|
| start | Number | The starting point of these results. Usefull for pagination |
| requestedCount | Number | The number of items requested in the search request |
| returnedCount | Number | The number of returned items. Might be lower than the requested count if fewer items than the requested count match the query |
| totalCount | Number | The total number or items matching the query |
| results | Object | The items matching the search query. If the format is html then this property will not exist. |
Example of a response with rendered HTML:
{
"success": true,
"query": "*",
"products": {
"start": 0,
"requestedCount": 5,
"returnedCount": 5,
"totalCount": 12
},
"categories": {
"start": 0,
"requestedCount": 5,
"returnedCount": 4,
"totalCount": 4
},
"html": "<! -- the html rendered from the liquid template configured on My Hello Retail -->",
}
-
The reason for supporting text/plain is to allow requests to this endpoint, made from the browser, to be categorized as simple thereby avoiding CORS preflight requests. You can read more here https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests ↩