For dev - Product Filter & Search API

In this article, we want to introduce our Product Filter & Search API and what you can do with it.

Description

Product Filter & Search API lets you query the filter tree and products for rendering in frontend store's theme

What can you do with Product Filter & Search API

  • GET /bc-sf-filter/filter

    Retrieve collections, products, and filter trees (if required) for a particular store

  • GET /bc-sf-filter/search

    Retrieve collections, products, pages and filter trees (if required) for a particular store based on a search query

Endpoints

GET /bc-sf-filter/filter

GET /bc-sf-filter/search

GET /bc-sf-filter/search/collections

GET /bc-sf-filter/search/pages

Retrieve collections, products, pages and filter trees (if required) for a particular store based on request params

Request Param

Param Description
shop The store name of the current request. E.g: bc-sf-filter-demo2.myshopify.com  

*Required
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 Returns a specific page of results

(default: 0)
limit Returns up to this many results per page

(default: 20, maximum: 70)
price_mode Sort products by price min or price max

Allowed values:
- min: Use Price Min (default)
- max: Use Price Max
product_available Returns products by available status 

Allowed values: 
- true (default) 
- false
variant_available Returns products by 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)
build_filter_tree Returns with the filter tree or not. 

E.g: For the collection page, from the second page, we don't need to build the filter tree as it is not different from the first page. This would help to reduce the workload of the server.

Allowed values:
- true
- false (default)
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 AND condition.

E.g: For an array of tag = ['Apple', 'Samsung', 'lg'], the API filters results with the following values ['Apple', 'apple,'] AND ['Samsung', 'samsung'] AND ['lg']

Please remember the tag param is different from the pf_t_* params created by the filter options of a filter tree
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. 
zero_options
For Filter Tree - Returns Filter Option Values with zero products or not. This param only works with Manual Values Filter Option.

Allowed values:
- true
- false (default)
sort Sort results by one of the following criteria

[
'manual',
'title-ascending',
'title-descending',
'title-s-ascending',
'title-s-descending',
'price-ascending',
'price-descending',
'variant-price-ascending',
'variant-price-descending',
'sale-ascending',
'sale-descending',
'published-ascending',
'published-descending',
'created-ascending',
'created-descending',
'best-selling',
'relevance',
'best-selling-ascending',
'best-selling-descending',
'relevance-ascending',
'relevance-descending',
'review-ratings-ascending',
'review-ratings-descending',
'extra-sort1-ascending',
'extra-sort1-descending',
'extra-sort2-ascending',
'extra-sort2-descending',
'extra-sort3-ascending',
'extra-sort3-descending',
]
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', '
created_at',
'published_at',
'best_selling_rank'
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
q Search Query String
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.
pf_* The generated params by the selected filter option values in the filter tree. The API filters the products based on these params. Accept string or array values.

The param pf_* must be exactly like the filter option id in the filter tree for it to work correctly. If no filter option id is found for a particular pf_* param, the API skips that param.
tag_mode Whether to use AND or OR condition

Allowed values:
- 1 (AND) (default)
- 2 (OR) 
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
from_cache 'from_cache': false

Whether the returned data is from cache or not
products 'products': [
 product item 1,
 product item 2,
 ...
]

A list of products

View Product Properties
filter 'filter':  {
'options': [
 filter option 1,
 filter option 2,
]
 ...
}

Filter Tree with Filter Options. This property is returned or not depending on the request param build_filter_tree=false

View Filter Tree Option Properties

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": "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
          }
        ]
      }
    ]
  }
}