For dev - Instant Search API
Description
Suggestion/Instant Search API lets you query the products based on the search query. This API serves the Instant Search Box of the front store.
What can you do with Filter & Search API?
GET /bc-sf-filter/search/suggest
Retrieve collections and products for instant search for a particular store.
Endpoints
GET /bc-sf-filter/search/suggest
Retrieve collections and products for a particular store based on request params and search queries.
Request params
| Param | Description |
|---|---|
| shop | The store name of the current request. E.g: bc-sf-filter-demo2.myshopify.com *Required |
| q | Search Query String *Required |
| excluded_search_fields | Excluded the search fields Allowed values:
|
| event_type | The event when this request is triggered. The API only returns the event_type based on the request param |
| call_back | The callback function for JSONP request. If no call_back param is included. The API returns pure JSON |
| page_limit | Returns up to this many page type results per page (default: 3, maximum: 10) |
| collection_limit | Returns up to this many collection type results per page (default: 3, maximum: 10) |
| product_limit | Returns up to this many product type results per page (default: 5, maximum: 10) |
| suggestion_limit | Returns up to this many suggestion type results per page (default: 4, maximum: 10) |
| dym_limit | Returns up to this many 'did you mean' type results per page (default: 3, maximum: 5) |
| product_available | Returns products by available status Allowed values:
|
| variant_available | Returns products with variant available status. In Shopify, a product might have property available set to true but one of their variants' available might be false. Allowed values:
|
| scope | Returns products by the display scope of the products. Accept string or array values. Allowed values:
|
| collection_scope | Returns products by the collections the products belong to. The integer value is required. (default: 0) |
| product_type | Filter results by product type. |
| vendor | Filter results by the product vendor. |
| tag | Filter results by tags. Accept string or array values. Note: For any tag value, the API filter results by exact tag value and its lowercase value. For array value, the API uses the OR condition. E.g: For an array of tag = ['Apple', 'Samsung', 'lg'], the API filters results with the following values ['Apple', 'apple,'] OR ['Samsung', 'samsung'] OR ['lg'] |
| tag_mode | Whether to use OR or AND condition for the tag search Allowed values
|
| h_options | Skip the results with specific tags. Accept string or array values. For array value, the API uses the OR condition. E.g: For an array of h_options = ['bad', 'out'], the API skips the products with the tag pfs:hidden:bad OR pfs:hidden:out. |
| sort_first | Sort products first with one of the following fields before applying the above sorting of sort param. Allowed values:
|
| sort_first_mode | Sort First in Ascending or Descending. Allowed values:
|
| sort | Add sort param to change the sorting of product list in the instant search. |
| lang | Filter results by a specific translated language. Allowed values:
|
| fuzzy | Enable the fuzziness search based on the search query param or not. Allowed values:
E.g: If fuzzy=1, a search term like 'boots' will match the following documents that have the words like 'boats', 'books', etc. If fuzzy=2, a search term like 'bear' will match the documents that have the words 'been', 'benz', etc. If fuzzy=false, requires exact match of the search term. |
| reduce_min_match | Reduces the min match requirements in the search query Allowed values:
|
| full_min_match | Filter the results that match all the words in search query. Allowed values:
E.g: If full_min_match=true, and the search query is "Bat Man Hero", the API will look for all the documents that have 3 words "bat", "man", "hero". Otherwise, the API will use the default min match value, which is 85% of search query or reduce_min_match param value. |
| boost | Whether to sort the results with the boost field. In order for this param to work correctly, a custom function is required to calculate the boost value per products. |
| re_run_if_typo (updated with new search 14/02/2023) | Run query suggestion again with fixed typo query if given param q is return 0 product. Precondition
Allowed values:
|
Response Properties
| Param | Description | Note |
| total_product | 'total_product': 1 Total Product Returned |
|
| error | 'error': 'not_found' This property error is returned only when having any error |
|
| products | 'products': [ product item 1, product item 2, ... ] A list of products View Product Properties |
|
| pages | 'pages': [ { 'handle': 'how-rc-works', // Handle of the page/article 'id': 52309858852, // Id of the collection 'title': 'How the RC Works' // Title of the page/article 'url': '/blogs/how-to/how-rc-works' // Full path of page/article } ] A list of pages/articles |
|
| collections | 'collections': [ { "handle": "simple-top", // Handle of the collection "id": 43309858852, // Id of the collection "title": "Simple Top" // Title of the collection } ] A list of collections |
|
| suggestions | 'suggestions': [ 'top', 'shirt' ] A list of search suggestions for end user |
|
| did_you_mean | 'did_you_mean': [ 'laptop' ] A list of did you mean words that we suppose the customer has typed some wrong characters |
|
| query | 'query': 'bottom' Returns the query based on the prev_query param |
|
| prev_query | 'prev_query': 'botto' Returns the prev_query based on the prev_query param for frontend logic requirement |
|
| correct_query (updated with new search 14/02/2023) | value use to run suggestion again after typo service return the fixed query | |
| scoped_suggestions | "scoped_suggestions": { "mix dress": { "categories": [ "Outerwear" ], "vendors": [ "Converse", "Fendi" ], "product_types": [ "Converse", "Fendi" ], "categories": [ "Converse", "Fendi" ] }, "purple mix dress": {}, "mesh mix dress": {} } |
If the applyScopedSuggestion feature flag is enabled |
Response Example
{
"total_product": 1,
"from_cache": false,
"products": [
{
"id": 8584719122,
"available": true,
"title": "Intelligent Linen Chair",
"body_html": "",
"vendor": "Hermes",
"product_type": "Dresses",
"handle": "intelligent-linen-chair",
"created_at": "2016-12-10T19:33:22-05:00",
"updated_at": "2017-10-14T00:38:31-04:00",
"published_at": "2016-12-10T19:33:03-05:00",
"published_scope": "web",
"template_suffix": null,
"tags": [
"collection:tops",
"style:Arty"
],
"price_min": 58,
"price_max": 146,
"compare_at_price_min": null,
"compare_at_price_max": null,
"percent_sale_min": 0,
"synced_at_v2": 1550862995,
"images": {
"1": "https://cdn.shopify.com/s/files/1/1651/2159/products/1_2e3ce250-465b-41e4-9ede-4e520d92dffd.jpg?v=1481416402",
"2": "https://cdn.shopify.com/s/files/1/1651/2159/products/4_fa3ba281-e7d6-4c54-b16d-76ab7799a49a.jpg?v=1481416402"
},
"images_info": [
{
"id": 17677375442,
"position": 1,
"src": "https://cdn.shopify.com/s/files/1/1651/2159/products/1_2e3ce250-465b-41e4-9ede-4e520d92dffd.jpg?v=1481416402",
"width": 762,
"height": 1100
},
{
"id": 17677375506,
"position": 2,
"src": "https://cdn.shopify.com/s/files/1/1651/2159/products/4_fa3ba281-e7d6-4c54-b16d-76ab7799a49a.jpg?v=1481416402",
"width": 762,
"height": 1100
}
],
"collections": [
{
"id": 357407890,
"handle": "tops",
"title": "Tops",
"featured": false,
"sort_value": "0000000022"
},
{
"id": 34592456740,
"handle": "all",
"title": "Collection All",
"featured": false,
"sort_value": "0000000259"
}
],
"options_with_values": [
{
"name": "size",
"label": "Size",
"values": [
{
"title": "S",
"image": null
},
{
"title": "M",
"image": null
},
{
"title": "XL",
"image": null
},
{
"title": "XXL",
"image": null
}
]
},
{
"name": "color",
"label": "Color",
"values": [
{
"title": "Yellow",
"image": null
}
]
}
],
"variants": [
{
"available": true,
"merged_options": [
"color:Yellow",
"size:S/M"
],
"image": null,
"id": 28652161170,
"title": "S / Yellow",
"sku": "",
"barcode": "",
"inventory_management": null,
"inventory_policy": "deny",
"inventory_quantity": 7,
"price": "85.50",
"compare_at_price": null
},
{
"available": true,
"merged_options": [
"color:Yellow",
"size:S/M"
],
"image": null,
"id": 28652161234,
"title": "M / Yellow",
"sku": "intelligent-linen-chair-m",
"barcode": "",
"inventory_management": null,
"inventory_policy": "deny",
"inventory_quantity": 1,
"price": "86.50",
"compare_at_price": null
},
{
"available": true,
"merged_options": [
"color:Yellow",
"size:XXL"
],
"image": null,
"id": 28652161298,
"title": "XL / Yellow",
"sku": "intelligent-linen-chair-xl",
"barcode": "",
"inventory_management": null,
"inventory_policy": "deny",
"inventory_quantity": 2,
"price": "146.00",
"compare_at_price": null
},
{
"available": true,
"merged_options": [
"color:Yellow",
"size:XXL"
],
"image": null,
"id": 28652161426,
"title": "XXL / Yellow",
"sku": "intelligent-linen-chair-xxl",
"barcode": "",
"inventory_management": null,
"inventory_policy": "deny",
"inventory_quantity": 1,
"price": "58.00",
"compare_at_price": null
}
],
"skus": [
"intelligent-linen-chair-m",
"intelligent-linen-chair-xl",
"intelligent-linen-chair-xxl"
],
"barcodes": [
],
"weight_min": 56,
"weight_max": 879,
"merged_search_engram": "dresses hermes",
"merged_rsearch": "Intelligent Linen Chair",
"metafields": [
],
"review_ratings": 0
}
],
"filter": {
"options": [
{
"status": "active",
"position": "0",
"label": "Collection",
"filterOptionId": "pf_c_collection",
"filterType": "collection",
"displayType": "list",
"selectType": "single",
"valueType": "specific",
"manualValues": [
{
"handle": "tops",
"label": "Tops",
"id": "357407890"
},
{
"handle": "intimates",
"label": "Intimates",
"id": "357408082"
},
{
"handle": "dresses",
"label": "Dresses",
"id": "357408018"
},
{
"handle": "swimwear",
"label": "Swimwear",
"id": "357408210"
}
],
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": true,
"showSearchBoxFilterMobile": true,
"keepValuesStatic": false,
"activeCollectionAll": true,
"tooltip": "Test",
"showMoreType": "scrollbar",
"sortType": "key-asc",
"sortManualValues": false,
"displayAllValuesInUppercaseForm": false,
"values": [
{
"key": "357407890",
"label": "Tops",
"handle": "tops",
"tags": null,
"doc_count": 1
},
{
"key": "357408082",
"label": "Intimates",
"handle": "intimates",
"tags": null,
"doc_count": 0
},
{
"key": "357408018",
"label": "Dresses",
"handle": "dresses",
"tags": null,
"doc_count": 0
},
{
"key": "357408210",
"label": "Swimwear",
"handle": "swimwear",
"tags": null,
"doc_count": 0
}
]
},
{
"status": "active",
"position": "1",
"label": "Product Type",
"filterOptionId": "pf_pt_product_type",
"filterType": "product_type",
"displayType": "list",
"selectType": "multiple",
"valueType": "all",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"tooltip": "Test2",
"showMoreType": "viewmore",
"sortType": "doc_count-desc",
"sortManualValues": false,
"displayAllValuesInUppercaseForm": false,
"values": [
{
"key": "Accessories",
"doc_count": 1
},
{
"key": "Dresses",
"doc_count": 1
}
]
},
{
"status": "active",
"position": "2",
"label": "Pris",
"filterOptionId": "pf_p_pris",
"filterType": "price",
"displayType": "range",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"sliderRange": "4",
"sliderStep": 1,
"sliderDelimiter": null,
"tooltip": "This is the price filter option with Range slider",
"values": {
"max": 58,
"min": 58
}
},
{
"status": "active",
"position": "3",
"label": "Vendor",
"filterOptionId": "pf_v_vendor",
"filterType": "vendor",
"displayType": "list",
"selectType": "multiple",
"valueType": "all",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"tooltip": null,
"showMoreType": "viewmore",
"sortType": "key-desc",
"sortManualValues": false,
"values": [
{
"key": "Hermes",
"doc_count": 1
}
]
},
{
"status": "active",
"position": "4",
"label": "Review Rating",
"filterOptionId": "pf_r_review_rating",
"filterType": "review_ratings",
"displayType": "rating",
"selectType": "single",
"valueType": null,
"manualValues": null,
"isCollapsePC": null,
"isCollapseMobile": null,
"prefix": null,
"keepValuesStatic": null,
"activeCollectionAll": null,
"sliderRange": null,
"sliderStep": null,
"sliderEnableThousand": null,
"sliderDelimiter": null,
"showMoreType": null,
"sortType": null,
"sortManualValues": null,
"values": [
{
"key": "1.0-*",
"from": 1,
"doc_count": 0
},
{
"key": "2.0-*",
"from": 2,
"doc_count": 0
},
{
"key": "3.0-*",
"from": 3,
"doc_count": 0
},
{
"key": "4.0-*",
"from": 4,
"doc_count": 0
},
{
"key": "5.0-*",
"from": 5,
"doc_count": 0
}
]
},
{
"status": "active",
"position": "5",
"label": "Color Option",
"filterOptionId": "pf_opt_color",
"filterType": "opt_color",
"displayType": "swatch",
"selectType": "multiple",
"valueType": "all",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"tooltip": null,
"showMoreType": "scrollbar",
"sortType": "key-asc",
"sortManualValues": false,
"displayAllValuesInUppercaseForm": false,
"values": [
{
"key": "White",
"doc_count": 1
},
{
"key": "Yellow",
"doc_count": 1
},
{
"key": "Black",
"doc_count": 1
}
]
},
{
"status": "active",
"position": "6",
"label": "Color Type",
"filterOptionId": "pf_t_color_type",
"filterType": "tag",
"displayType": "swatch",
"selectType": "multiple",
"valueType": "all",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"prefix": "color\\:",
"tooltip": null,
"showMoreType": "scrollbar",
"sortType": "key-desc",
"sortManualValues": false,
"useAndCondition": false,
"displayAllValuesInUppercaseForm": false,
"values": [
]
},
{
"status": "active",
"position": "7",
"label": "Stock Status",
"filterOptionId": "pf_st_stock_status",
"filterType": "stock",
"displayType": "list",
"manualValues": [
{
"label": "In Stock",
"key": "in-stock",
"doc_count": 1
},
{
"label": "Out of Stock",
"key": "out-of-stock"
}
],
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"tooltip": null,
"showMoreType": "scrollbar",
"sortType": "key-asc",
"sortManualValues": false,
"values": [
{
"label": "In Stock",
"key": "in-stock",
"doc_count": 1
},
{
"label": "Out of Stock",
"key": "out-of-stock"
}
]
},
{
"status": "active",
"position": "8",
"label": "Style",
"filterOptionId": "pf_t_style",
"filterType": "tag",
"displayType": "list",
"selectType": "multiple",
"valueType": "all",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"prefix": "style\\:",
"tooltip": null,
"showMoreType": "viewmore_scrollbar",
"sortType": "key-asc",
"sortManualValues": false,
"useAndCondition": true,
"values": [
{
"key": "style:Arty",
"doc_count": 1
}
]
},
{
"status": "active",
"position": "9",
"label": "außerdem",
"filterOptionId": "pf_ps_ausserdem",
"filterType": "percent_sale",
"displayType": "list",
"selectType": "multiple",
"manualValues": [
":20",
"20:40",
"40:60",
"60:80",
"80:"
],
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"tooltip": null,
"showMoreType": "scrollbar",
"sortType": "key-asc",
"sortManualValues": false,
"values": [
{
"key": "*-20",
"to": 20,
"doc_count": 0
},
{
"key": "20-40",
"from": 20,
"to": 40,
"doc_count": 0
},
{
"key": "40-60",
"from": 40,
"to": 60,
"doc_count": 0
},
{
"key": "60-80",
"from": 60,
"to": 80,
"doc_count": 0
},
{
"key": "80.0-*",
"from": 80,
"doc_count": 0
}
]
},
{
"status": "disabled",
"position": "10",
"label": "颈线",
"filterOptionId": "pf_t_",
"filterType": "tag",
"displayType": "swatch",
"selectType": "multiple",
"valueType": "all",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"prefix": "",
"tooltip": null,
"showMoreType": "scrollbar",
"sortType": "key-asc",
"sortManualValues": false
},
{
"status": "active",
"position": "11",
"label": "Cloth Size",
"filterOptionId": "pf_t_cloth_size",
"filterType": "tag",
"displayType": "list",
"selectType": "multiple",
"valueType": "all",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"prefix": "",
"tooltip": null,
"showMoreType": "scrollbar",
"sortType": "key-asc",
"sortManualValues": false,
"values": [
{
"key": "collection:tops",
"doc_count": 1
},
{
"key": "style:Arty",
"doc_count": 1
}
]
},
{
"status": "active",
"position": "12",
"label": "Test",
"filterOptionId": "pf_t_test",
"filterType": "tag",
"displayType": "list",
"selectType": "multiple",
"valueType": "all",
"manualValues": null,
"isCollapsePC": false,
"isCollapseMobile": false,
"showSearchBoxFilterPC": false,
"showSearchBoxFilterMobile": false,
"prefix": "",
"tooltip": null,
"showMoreType": "scrollbar",
"sortType": "key-asc",
"sortManualValues": false,
"useAndCondition": true,
"values": [
{
"key": "collection:tops",
"doc_count": 1
},
{
"key": "style:Arty",
"doc_count": 1
}
]
}
]
}
}