- API reference
Apr 01, 2023
usf object
On this page
/search and /instantsearch API - Search products
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 a JSON data 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.
© Sobooster - Privacy Policy