For dev - Boost AI Search & Discovery API

📖 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.

On this page

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

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

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

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

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

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

View Product Properties


Array
filter

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


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

If you need any further assistance, please do not hesitate to contact us at support@boostcommerce.net.

Related Articles