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.In this article
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
}
]
}
]
}
}