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 by categories and pages in unavailable for free plans.
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"}
