For dev - Instant Search API
In this article
Description
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 |
| suggest_types | Filter results by item types. Accept Array Values Allowed values: - products - pages - collections - suggestions - did_you_mean - ['products', 'pages', 'collections', 'suggestions', 'did_you_mean'] (default) |
| 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 the 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: 6, maximum: 10) |
| suggestion_limit | Returns up to this many suggestion type results per page (default: 3, 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: - true (default) - false |
| 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: - true - false (default) |
| scope | Returns products by the display scope of the products. Accept string or array values. Allowed values: - global - Global - web - ['global', 'Global', 'web'] (default) |
| 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 - 1: AND - 2: OR (default) |
| 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: - available - extra_sort1 - extra_sort2 - extra_sort3 - false (default) |
| sort_first_mode | Sort First in Ascending or Descending. Allowed values: - asc - desc (default) |
| lang | Filter results by a specific translated language. Allowed values: - false (default) - tl1: Translated Language 1 - tl2: Translated Language 2 |
| fuzzy | Enable the fuzziness search based on the search query param or not. Allowed values: - false: Require Exact match - true: Enable fuzziness at 2 characters (default) - 1: Enable fuzziness at 1 character only - 2: Enable fuzziness at 2 characters E.g: If fuzzy=1, a search term like 'boots' will match the following documents that have 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 an exact match of the search term. Besides, you could also modify the level of Fuzzy Search by using the in-app "Advanced settings" setting. Click here for the instruction. |
| reduce_min_match | Reduces the min match requirements in the search query Allowed values: - false (default): results to 85% match - true: results in a 50% match - An Integer Number: requires min match exact this number |
| full_min_match | Filter the results that match all the words in the search query. Allowed values: - false (default) - true 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 the 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 product. |
| enable_plus_character_search | Enable + character in the search term Allowed values: - true - false (default) |
Response Properties
| Param | Description |
| 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 |
| 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 |
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
}
]
}
]
}
}