Skip to main content
For dev - Boost AI Search & Discovery API
Thomas Ta avatar
Written by Thomas Ta
Updated over a week ago

πŸ“– Welcome to the Boost Commerce Boost AI Search & Discovery API Guide. In this guide, we'll introduce you to our API and show you how to use it to enhance your store's capabilities. To get started, you'll need to know the API domain where our services are hosted. The domain for our API is https://services.mybcapps.com.


Description

The Boost AI Search & Discovery API allows you to interact with our filter tree and products, enabling you to seamlessly integrate these features into your store's frontend theme.


What can you do with Boost AI Search & Discovery API

  • GET /bc-sf-filter/filter

    Use this endpoint to retrieve collections, products, and filter trees (if required) for a particular store. Here's an example URL:

GET https://services.mybcapps.com/bc-sf-filter/filter
  • GET /bc-sf-filter/search

    This endpoint retrieves collections, products, pages, and filter trees (if required) based on a search query. Example URL:

GET https://services.mybcapps.com/bc-sf-filter/search

Endpoints

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

Request Params

Param

Description

Value Type

Values

Default Value

shop

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


​

String

event_type

The event when this request is triggered. E.g: filter, page (go to another page), sort, etc.


​

String

callback

The callback function for JSONP request. If no call_back param is included, the API returns pure JSON


​

String

page

Returns a specific page of results

Integer

0

limit

Returns up to this many results per page.

Note: We support up to 70 products per page

Integer

20

price_mode

Sorts products by Price min or Price max


​

String

  • min (Use Price Min)

  • max (Use Price Max)

min

product_available

Returns products by available status


​

Boolean

  • true

  • false

true

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.


​

Boolean

  • true

  • false

false

scope

Returns products by the display scope of the products.


​

String

Array

  • global

  • Global

  • web

  • ['global, 'Global', 'web']

['global, 'Global', 'web']

collection_scope

Returns products by the Collection Id

Integer

0 (collections/all)

build_filter_tree

Depend on each situation, our Filter tree needs to be rebuilt or not. This would help to reduce the workload of our server.

  • None-rebuilt:

    • Go to another page

    • Change sorting, display type, number of products

  • Rebuilt:

    • Filter


​

Boolean

  • true

  • false

false

check_cache

Should the response be returned from cache or not.

Deprecated


​

Boolean

  • true

  • false

false

tag

Filter results by tags.

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 with the pf_t_* params created by the filter options of a filter tree

String

Array

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.

String

Array

zero_options

For Filter Tree - Returns Filter Option Values with zero products or not

Note: This param only works with Manual Values Filter Option.

Boolean

  • true

  • false

false

sort

Sort results by one of the following criteria

Array

[

'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',

]


​

[

'manual',

'title-ascending',

'title-descending',

'price-ascending',

'price-descending'

'created-ascending',

'created-descending',

'best-selling

']


​

sort_first

Sort products first with one of the following fields before applying the above sorting of sort param.

String

  • available

  • extra_sort1

  • extra_sort2

  • extra_sort3

  • false

false

sort_first_mode

Sort First in Ascending or Descending.

String

  • asc

  • desc

desc

lang

Filter results by a specific translated language.

Boolean

String

  • false

  • tl1: Translated Language 1

  • tl2: Translated Language 2

false

q

Search Query String (Only available in Search page)

excluded_search_fields

Excluded the search fields, means our system doesn't get that field as the Search condition

Array

  • []

  • ['body_html'] (exclude Product Description)

[]

fuzzy

Enable the fuzziness search based on the search query param or not.

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.

Boolean

Integer

  • false (Require Exact match)

  • true (Enable fuzziness at 2 characters)

  • 1 (Enable fuzziness at 1 character only)

  • 2 (Enable fuzziness at 2 characters)

true

reduce_min_match

Reduces the min match requirements in the search query

Boolean

Integer

  • false (results to 85% match)

  • true: (results to 50% match)

  • An Integer Number (requires min match exact this number)

false

full_min_match

Filter the results that match all the words in search query.

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.

Boolean

  • false

  • true

false

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.

pf_*

The generated params by the selected filter option values in the filter tree. The API filters the products based on the these params. Accept string or array values.

The param pf_* must be exact 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.

String

tag_mode

Whether to use AND or OR condition

Boolean

Integer

  • 1 (AND)

  • 2 (OR)

1

search_filter_tree

Display search filter tree as default.

Boolean

  • true

  • false

false

disable_sku_query

We have our own query term for the search term that is formatted like SKU (a word with numbers).

In some cases when we don't want to use this query, set this parameter to true.

Boolean

  • true

  • false

false

enable_plus_character_search

Enable search term contains + character

Boolean

  • true

  • false

false

priority_search_first

Enable search based on field product.priority_search .

Note about the field priority_search:

  • This field has the highest priority, higher than the title.

  • By default this field will be empty, we need to add it with the custom function.

  • true

  • false

false

return_all_currency_fields

Return all currency fields like

price_min_usd, price_max_usd ……

NEW

Boolean

  • true

  • false

true


​

Response Properties

Param

Description

Value Type

Values

total_product

Total Products


​

Integer

products

A list of products with their detail


​

Array

filter

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


​

Array

from_cache

Whether the returned data is from cache or not

Boolean

  • true

  • false

error

This property error is returned only when having any error

String

typo

output from typo tolerance service

Object

undefine

Response Example

{
"total_product": 1,
"from_cache": false,
"typo": {
"correctQuery": "compact",
"correctContent": "compact",
"suggestions": ["compact", "context"]
},
"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,
"Here is a properly formatted version of your JavaScript code snippet:

```javascript
{
"total_product": 1,
"from_cache": false,
"typo": {
"correctQuery": "compact",
"correctContent": "compact",
"suggestions": ["compact", "context"]
},
"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,
The JSON data you provided appears to be a structured response from a search or filtering system, listing a single product ("Intelligent Linen Chair") along with typographical suggestions and filtering options. Here's a more readable format for your JSON data:

```json
{
"total_product": 1,
"from_cache": false,
"typo": {
"correctQuery": "compact",
"correctContent": "compact",
"suggestions": [
"compact",
"context"
]
},
"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-lHere's your reformatted JSON data to enhance readability:

```json
{
"total_product": 1,
"from_cache": false,
"typo": {
"correctQuery": "compact",
"correctContent": "compact",
"suggestions": ["compact", "context"]
},
"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": "Here's the reformatted JSON data for better readability:

```json
{
"total_product": 1,
"from_cache": false,
"typo": {
"correctQuery": "compact",
"correctContent": "compact",
"suggestions": ["compact", "context"]
},
"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": ["Here's a reformatted version of your JavaScript snippet, preserving the original content and improving readability with proper formatting:

```javascript
var boostPFSFilterConfig = {
general: {
// Settings list
limit: boostPFSThemeConfig.custom.products_per_page,
loadProductFirst: true,
styleScrollToTop: 'style2'
}
};


​

If you need any further assistance, please do not hesitate to contact us at [email protected].

Did this answer your question?