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 Search Results 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 the details below. | Attributes available for the test search | |
| restrictBy[attribute] | Product filter by the specified attribute. See the details below. | Attributes available for filtering | |
| unionBy[attribute][min] | Selects the minimum of the attribute values and replaces the specified attribute. See the details below. | ||
| sortBy | Sorts the product search results by the specified attribute or by relevance. See the details below. | 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 the sortBy parameter
Sorts the products in search results by one of these values:
- relevance
- title – product title
- created – created date
- price
- discount
- reviews_average_score – rating from third-party applications of product reviews
- total_reviews – the total number of reviews from third-party applications of product reviews
- sales_amount – bestselling
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) For Shopify users with the Filter tree feature: | 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"}
