- API reference
Client request API
On this page
Sobooster API is for integrating our smart and lightning-fast search & filter functionality into your applications. For example you can integrate our API into your websites, desktop apps, and mobile apps to query indexed data.
API key and Endpoint URL
You must have a Sobooster account to use the Search API. Please access the 'Status & usage' tab on the Settings page to retrieve the following credentials.
- Client API Key: e.g.
c811efb1-f10b-482c-b3d7-0f49f7c30f3e - Cloud Search Endpoint URL: e.g.
svc-1001-usf.hotyon.com
If you have multiple stores with Sobooster, please note it is likely that each of them will have totally different Client API Keys and subdomains assigned.
Search and Filter Requests
This API returns the products or variants matching the search term. Each store is given an ID to the corresponding service ID on our servers which is identified in the URL like https://svc-1001-usf.hotyon.com. In the aforementioned URL the service ID is 1001.
How to get a service ID and API key of a store.
After installing the widget to your theme, Open browser developer tool and click on XHR tab then navigate to <your-store-domain>/search (for Shopify platform). You will then see there is a request similar to https://svc-1001-usf.hotyon.com/search?q=&apiKey=c811efb1-f10b-482c-b3d7-0f49f7c30f3e. You can see that the service ID is 1001 and the apiKey is c811efb1-f10b-482c-b3d7-0f49f7c30f3e.
Query parameters
| Name | Data type | Description |
|---|---|---|
| apiKey | Guid | The API key of the store. This parameter is required. |
| q | String | The search term. |
| collection | String or Number | The collection handle/url name or collection ID. e.g. collection handle t-shirt or collection id 123456789. This parameter is optional. |
| skip | Number | The number of items to skip. |
| take | Number | The number of items to take. |
| sort | String | The sort field. Available sort fields are:
|
| locale | String | The store lowercased locale. e.g. en. This parameter is optional. If not specified, the app will use the default store locale. |
| customerTags | String | The customer tags delimited by , character. This parameter is optional. |
| separateVariants | Boolean | 0 to disable Separate variants as products feature. This param is only used if the premium feature Separate Variants as Products is enabled |
| showFacets | Boolean | Indicates whether to show facets. 1 to show, 0 to hide. Default is 1 if the request path is /search, 0 if the path is /instantsearch |
| showSuggestions | Boolean | Indicates whether to show suggestions. 1 to show, 0 to hide. Default is 0 if the request path is /search, 1 if the path is /instantsearch |
| showCollections | Boolean | Indicates whether to show collections. 1 to show, 0 to hide. Default is 0 if the request path is /search, 1 if the path is /instantsearch |
| showPages | Boolean | Indicates whether to show pages. 1 to show, 0 to hide. Default is 0 if the request path is /search, 1 if the path is /instantsearch |
| getProductExtra | Boolean | Indicates whether to get product extra info. 1 to get, 0 to ignore. Default is 1 if the platform is BigCommerce. This param is not used in Shopify and Magento platforms |
| getProductDescription | Boolean | Indicates whether to get product description. 1 to get, 0 to ignore. Default is 1 - get product description. |
For example if the service ID is 1001, apiKey is c811efb1-f10b-482c-b3d7-0f49f7c30f3e and search term is abc the GET query should be: https://svc-1001-usf.hotyon.com/search?q=abc&apiKey=c811efb1-f10b-482c-b3d7-0f49f7c30f3e.
Response
The response is in JSON format with structure similar to the following:
{
"data": {
"query": "",
"totalCollections": 0,
"collections": null,
"totalPages": 0,
"pages": null,
"suggestions": null,
"total": 15,
"items": [
{
"id": 4801102676048,
"productType": "",
"title": "Red Dress",
"description": "",
"collections": [
161809956944,
168195293264
],
"tags": [],
"urlName": "red-dress",
"vendor": "Test get ai commerce",
"date": "2021-04-29T05:17:16.0000000Z",
"variants": [
{
"id": 32879316271184,
"sku": "876876BBH",
"barcode": null,
"available": 0,
"price": 0,
"weight": 99990000,
"compareAtPrice": 0,
"imageIndex": -1,
"options": [
0
],
"metafields": [],
"flags": 0,
"locations": null
}
],
"selectedVariantId": null,
"images": [
{
"url": "//cdn.shopify.com/s/files/1/0262/8711/22172/products/logo.png?v=1600653487",
"alt": "",
"width": 200,
"height": 200
}
],
"metafields": [
{
"key": "review",
"value": "{\"count\":\"0\",\"avg\":0,\"product_id\":\"4801102676048\"}",
"valueType": "String",
"namespace": "ssw",
"description": null,
"fullName": "ssw.review"
},
{
"key": "ProductReviewsWidgetSnippet",
"value": "<span></span>",
"valueType": "String",
"namespace": "okendo",
"description": null,
"fullName": "okendo.ProductReviewsWidgetSnippet"
},
{
"key": "ProductListingSnippet",
"value": "<span></span>",
"valueType": "String",
"namespace": "okendo",
"description": null,
"fullName": "okendo.ProductListingSnippet"
},
{
"key": "summaryData",
"value": "{\"reviewCount\":0,\"reviewAverageValue\":\"0.0\"}",
"valueType": "String",
"namespace": "okendo",
"description": null,
"fullName": "okendo.summaryData"
}
],
"options": [
{
"name": "Shipping fee",
"values": [
"0"
]
}
],
"review": 0,
"reviewCount": 0,
"extra": null
}
],
"facets": [
{
"id": 1898887180,
"title": "Collection",
"facetName": "collections",
"multiple": 0,
"display": "List",
"sort": 1,
"maxHeight": "300px",
"labels": [
{
"label": "Furniture | Manual",
"value": 8,
"id": 161809956944
},
{
"label": "All items",
"value": 15,
"id": 168195293264
}
]
},
{
"id": 950479434,
"title": "Color",
"facetName": "option:Color",
"labelPrefix": "",
"multiple": 0,
"display": "List",
"sort": 1,
"maxHeight": "300px",
"labels": [
{
"label": "Navy",
"value": 1
}
]
}
],
"extra": {
"collections": [
{
"id": 168195293264,
"title": "All items",
"urlName": "all",
"description": null,
"imageUrl": null,
"sortOrder": "BestSelling"
}
]
}
}
}
14 Days Risk Free Trial. No credit card required. Cancel anytime.