Instant Search API

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: 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:
- true (default)
- false
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.
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
          }
        ]
      }
    ]
  }
}
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us