Search API

Search API is used to get search results.

Description of the search request

A request for getting search results is an HTTP GET request sent to the following addresses with parameters from the table below:

  • https://searchserverapi.com/search – only ID is returned for the found products, categories, pages
  • https://searchserverapi.com/getwidgets – besides ID, extended information for displaying the Instant Search Widget is returned
  • https://searchserverapi.com/getresults – besides ID, extended information for displaying the Instant Search Widget is returned
Parameter Description Value type Default value
apiKey Required parameter, public API key string
output Response format: json – output in JSON. jsonp – json with the callback function. It is used for the cross-domain call for code from javascript. Print is used for debugging in the browser. string (json, jsonp, print) json
callback Name of the callback function for the jsonp request. string
items Determines whether to return product search results. string (true, false) true
suggestions Determines whether to return information about suggestions string (true, false) false
categories Determines whether to return the search results on categories string (true, false) false
pages Determines whether to return the search results on pages string (true, false) false
facets Determines whether to return information about product filters string(true, false) false
q Search by string (by all attributes) string
queryBy[attribute] Product search by the specified attribute (see details below) Attributes available for the test search
restrictBy[attribute] Product filter by the specified attribute (see below) Attributes available for filtering
unionBy[attribute][min] Selects the minimum of the attribute values and replaces the specified attribute (see below)
sortBy Sorts the product search results by the specified attribute or by relevance relevance or attributes available for sorting relevance
sortOrder Sorting order. Does not affect the sorting by relevance string (asc, desc) asc
startIndex The order number of the product search results, starting from which the search results should be returned int 0
maxResults The number of products in the results int (0..250) 10
suggestionsMaxResults The number of suggestions in the search results int (0..50) 10
queryСorrection Enables the replacement of the original query with the correct value. Not valid when suggestions=false string (true, false) true
categoryStartIndex The order number of the category search results, starting from which the search results should be returned int 0
categoriesMaxResults The number of categories in the search results int (0..50) 50
pageStartIndex The order number of the page search results, starting from which the search results should be returned int 0
pagesMaxResults The number of pages in the results int (0..50) 50
facetsShowUnavailableOptions Determines whether to return options, for which nothing was found, in the filter array string (true,false) false
AutocompleteDescriptionLength The number of symbols in the returned product description. Valid only if the request is sent to /getwidgets int the value is taken from the settings of the instant search widget
ResultsDescriptionStrings The number of symbols in the returned product description = ResultsTitleStrings * 100. Pages, categories = ResultsTitleStrings * 150. Valid only if the request is sent to /getresults int the value is taken from the settings of the instant search widget

HTTP and HTTPS URLs are supported.

Search results by categories and pages are always sorted by relevance.

Description of the queryBy parameter

Using this parameter, you can search by a specific attribute:

  • queryBy[attribute]=search_string

Attributes have to be enabled for search.

Examples of using the queryBy parameter

  • http://searchserverapi.com/search?api_key=XXXXXXXXXXX&queryBy[title]=ipad

Description of the restrictBy parameter

Conditions for filtering results in the following format:

  • For attributes of the text type:
    • restrictBy[attribute]=value
    • restrictBy[attribute]=!value1 (not value1)
    • restrictBy[attribute]=value1|value2 (value1 or value2)
    • restrictBy[attribute]=value1,value2 (value1 and value2)
    • restrictBy[attribute]=value1,value2|value3|value4 (value1 and (value2 or value3 or value4)) (‘or’ operation has higher priority than ‘and’)
  • For the attributes of the float or int type:
    • restrictBy[attribute]=from,to ( from ⇐ attribute_value ⇐ to)
    • restrictBy[attribute]=,to ( -INF < attribute_value ⇐ to)
    • restrictBy[attribute]=from, (from ⇐ attribute_value < +INF)

All conditions that don’t comply with this rule will be ignored and won’t be taken into account in filtering.

Attributes have to be enabled for filtering.

If the values contain | or , symbols, they should be escaped in the request: \| or \,

Examples of using the restrictBy parameter

  • restrictBy[price]=0,145.4
  • restrictBy[price]=0,
  • restrictBy[category] = Keyboards
  • restrictBy[category] = Mouses|Keyboards
  • https://searchserverapi.com/search?api_key=XXXXXXXXXX&q=keyboard&restrictBy[color]=black&restrictBy[price]=0,150.4&restrictBy[category]=Keyboards

Description of the unionBy parameter

Conditions to replace the attribute value to the minimum one among values of other attributes.

As a rule, it is used to support prices for the user groups, for example, unionBy[price][min]=regural_price|wholesale_price replaces the price value with the minimum price from regural_price and wholesale_price.

If a filter was created by the price attribute, it will also use the replaced attribute value.

Examples of using the unionBy parameter

  • unionBy[price][min]=special_price
  • unionBy[price][min]=regural_price|wholesale_price

Description of response to the search query

Parameter Description Value type
totalItems The number of found products int
startIndex The current value of startIndex int
itemsPerPage The current value of maxResults int
currentItemCount The number of products on the current page int
correctedQuery The correct value of the q parameter (in case the q parameter has been corrected) string
categoryStartIndex The current value of  categoryStartIndex int
totalCategories The number of found categories int
pageStartIndex The current value of  pageStartIndex int
totalPages The number of found pages int
suggestions The array with suggestions array
items The array with products (see below) array
pages The array with pages (see below) array
categories The array with categories (see below) array
facets The array with filters (see below) array

If the request is sent to /getwidgets or /getresults arrays with products, categories, pages, it contains advanced information about the found elements:

  • product_id, title, description, link, price, list_price, quantity, product_code, image_link for products
  • category_id/page_id, title, link, image_link for categories and pages

Description of the filters array

Parameter Description Value type
title Filter name string
attribute Attribute name the filter was built with string
type Filter type select, range, slider
buckets Array with filter variants array

Description of the filter variants array

Parameter Description Value type Supported filter type
value Variant value float, int all
from Minimum value float, int range, slider, dynamic
to Maximum value float, int range, slider, dynamic
left Left value of the slider float, int slider
right Right value of the slider float, int slider
count Number of products that meet the conditions int all
selected Selected value string (true) all

An example of the request

curl -X GET "http://searchserverapi.com/getwidgets?apiKey=XXXXXXXXXX&q=test&facets=true&categories=true&pages=true&output=json"
 > {"totalItems":2,"startIndex":0,"itemsPerPage":10,"currentItemCount":2,"categoryStartIndex":0,"totalCategories":1,"pageStartIndex":0,"totalPages":1,"categories":[{"category_id":"1","title":"Category1 title","link":"https:\/\/example.com\/categories\/category1","image_link":"https:\/\/example.com\/images\/category1.jpg"}],"pages":[{"page_id":"1","title":"Page1 title","link":"https:\/\/example.com\/pages\/page1","image_link":"https:\/\/example.com\/images\/page1.jpg"}],"items":[{"product_id":"1","title":"Test product 1","description":"Test description","link":"https:\/\/example.com\/products\/product1","price":"12.0000","list_price":"0.0000","quantity":"","product_code":"product1","image_link":"https:\/\/example.com\/images\/product1.jpg"},{"product_id":"2","title":"Test product 2","description":"Test summary","link":"https:\/\/example.com\/products\/product2","price":"168.0000","list_price":"0.0000","quantity":"","product_code":"product2","image_link":"https:\/\/example.com\/images\/product2.jpg"}],"facets":[{"title":"Price","attribute":"price","type":"range","buckets":[{"value":"0.0000,150.0000","title":"from 0 to 150","from":"0.0000","to":"150.0000","count":"1"},{"value":"150.0000,800.0000","title":"from 150 to 800","from":"150.0000","to":"800.0000","count":"1"}]},{"title":"Categories","attribute":"categories","type":"select","appearance":"default","more_count":"0","buckets":[{"value":"Category1","count":1},{"value":"Category2","count":1}]}]}

Possible errors

  • EMPTY_API_KEY – The apiKey parameter is missing from the request.
  • INVALID_API_KEY – Invalid public key.
  • TOO_BIG_START_INDEX – The sum of the values of startIndex + maxResults parameters cannot exceed 100 000.
  • SEARCH_DATA_NOT_IMPORTED – The search data has not been imported
  • QUERY_STRING_TOO_LONG – The query string is too long ( q or queryBy[…]= … parameter exceeds 512 symbols).
  • ENGINE_REMOVED – The search database has been deleted as it was inactive.
  • ENGINE_DISABLED – The search ability is disabled for this API key.
  • ENGINE_SUSPENDED – The search ability is disabled for this API key due to non-payment.
  • QUERY_ATTRIBUTE_WASNT_FOUND – The queryBy parameter contains an invalid attribute or an attribute that is not specified for the search.
  • SORT_ATTRIBUTE_WASNT_FOUND – The sortBy parameter contains an invalid attribute or an attribute that is not available for sorting.
  • INDEX_ERROR – Index-related error (contact the Searchanise support team).
  • SYSTEM_ERROR – System-related error (contact the Searchanise support team)

An example of the response with an error message

{"error":"TOO_BIG_START_INDEX"}
Updated on August 5, 2022

Was this article helpful?

Related Articles

Need Support?
Can't find the answer you're looking for?
Contact Support
Back to top