Predictive Search API reference

The following calls can be submitted via the Predictive Search API to your Shopify shop.

For more information on how to use Predictive Search on your Shopify shop, see the following tutorials:

GET /search/suggest.json

Get predictive results for a specified search query. Predictive search supports suggestions for products, collections, pages, and articles.

GET /search/suggest.json?q=<query>&resources[type]=product

Query parameters

Query parameter Type Description
q (required) String The search query.
resources (required) Hash Requests resources results for the given query, based on the type and limit fields.
type (required) Comma-separated values Specifies the type of results requested. Valid values: product, page, article, collection.
limit (optional) Integer Limits the number of results returned. Default: 10. Min: 1. Max: 10.
options (optional) Hash Specifies options for the requested resources based on the unavailable_products and fields settings.
unavailable_products (optional) String Specifies whether to display results for unavailable products. The three possible options are show, hide, and last. Set to last to display unavailable products below other matching results. Set to hide to filter out unavailable products from the search results. Default: last.
fields (optional) Comma-separated values Specifies the list of fields to search on. Valid fields are: author, body, product_type, tag, title, variants.barcode, variants.sku, variants.title, and vendor. The default fields searched on are: title, product_type, variants.title, and vendor. For the best search experience, we recommend searching on the default field set or as few fields as possible.

Example request_object

{
  "q": "very-fast snowbo",
  "resources": {
    "type": "product",
    "limit": 5,
    "options": {
      "unavailable_products": "last",
      "fields": "title,product_type,variants.title"
    }
  }
}

Example call using jQuery:

jQuery.getJSON("/search/suggest.json", {
  "q": "jacket",
  "resources": {
    "type": "product",
    "limit": 4,
    "options": {
      "unavailable_products": "last",
      "fields": "title,product_type,variants.title"
    }
  }
}).done(function(response) {
  var productSuggestions = response.resources.results.products;

  if (productSuggestions.length > 0) {
    var firstProductSuggestion = productSuggestions[0];

    alert("The title of the first product suggestion is: " + firstProductSuggestion.title);
  }
});

Example call using Fetch:

fetch("/search/suggest.json?q=flannel&resources[type]=product&resources[limit]=4&resources[options][unavailable_products]=last")
.then(response => response.json())
.then(suggestions => {
  const productSuggestions = suggestions.resources.results.products;

  if (productSuggestions.length > 0) {
    var firstProductSuggestion = productSuggestions[0];

    alert(`The title of the first product suggestion is: ${
          firstProductSuggestion.title}`
    )
  }
});

Responses

Example response_object:

{
  "resources": {
    "results": {
      "products": ARRAY OF MATCHING product_object,
      "collections": ARRAY OF MATCHING collection_object,
      "pages": ARRAY OF MATCHING page_object,
      "articles": ARRAY OF MATCHING article_object
    }
  }
}

Example product_object:

{
  "available": BOOLEAN,
  "body": STRING w/HTML,
  "compare_at_price_max": DECIMAL ("0.00" when the product has no variants with a "compare_at_price"),
  "compare_at_price_min": DECIMAL ("0.00" when the product has no variants with a "compare_at_price"),
  "handle": STRING,
  "id": INTEGER,
  "image": STRING e.g, "https://cdn.shopify.com/s/...",
  "price": DECIMAL,
  "price_max": DECIMAL,
  "price_min": DECIMAL,
  "tags" : ARRAY OF STRING,
  "title": STRING,
  "type" : STRING,
  "url": STRING e.g, "/products/fast-snowboard?_pos=1&_psq=snowb&_ss=e&_v=1.0",
  "variants": [
   {
    "available": BOOLEAN,
    "compare_at_price": DECIMAL (nullable),
    "id": INTEGER,
    "image": STRING e.g, "https://cdn.shopify.com/s/...",
    "price": DECIMAL,
    "title": STRING,
    "url": STRING e.g, "/products/fast-snowboard?_pos=1&_psq=snowb&_ss=e&_v=1.0"
   }
  ],
 "vendor": STRING
}

Example collection_object:

{
  "body": STRING w/HTML,
  "handle": STRING,
  "id": INTEGER,
  "featured_image": { // (If a collection doesn't have an associated featured_image, then all of the properties of featured_image are set to null.)
    "alt": STRING,
    "width": INTEGER,
    "height": INTEGER,
    "aspect_ratio": DECIMAL,
    "url": STRING e.g, "https://cdn.shopify.com/s/..."
  },
  "published_at": STRING DATE,
  "title": STRING,
  "url": STRING e.g, "/collections/snowboards?_pos=1&_psq=sno&_ss=e&_v=1.0"
}

Example page_object:

{
  "author": STRING,
  "body": STRING w/HTML,
  "handle":STRING,
  "id": INTEGER,
  "published_at": STRING DATE,
  "title": STRING,
  "url": STRING e.g, "/pages/my-page?_pos=1&_psq=my&_ss=e&_v=1.0"
}

Example article_object:

{
  "author": STRING,
  "body": STRING w/HTML,
  "handle": STRING,
  "id": INTEGER,
  "image": STRING e.g, "https://cdn.shopify.com/s/...",
  "published_at": STRING DATE,
  "summary_html": STRING w/HTML,
  "tags": ARRAY OF STRING,
  "title": STRING,
  "url": STRING e.g, "/blogs/news/my-article?_pos=1&_psq=my&_ss=e&_v=1.0"
}

Error responses

All errors related to the request parameters are returned with a 422 status code and a relevant error message. The description field describes the request error.

{
  "status": "422",
  "message": "Invalid parameter error",
  "description": "Invalid option for `unavailable_products` parameter"
}

If your theme isn't using one of the supported languages listed above, then the API returns the following error:

{
  "status": "417",
  "message": "Expectation Failed",
  "description": "Unsupported shop primary locale"
}

Exceeding the request throttle limit will return a 429 status code with a relevant error message.

{
  "status": "429",
  "message": "Too many requests",
  "description": "Throttled"
}

In this case, the response will also contain an HTTP header with the Retry-After value in seconds.

Retry-After: 1

All other unexpected errors will return a 5xx status code.

Searchable properties

Results are based on different searchable properties, depending on the resource type included in your query.

Resource type Searchable properties
Products
  • body
  • product_type
  • tag
  • title
  • variants.barcode
  • variants.sku
  • variants.title
  • vendor
Pages
  • author
  • body
  • title
Articles
  • author
  • body
  • tag
  • title
Collections
  • title

Typo tolerance

Predictive search includes typo tolerance, which lets search terms containing typos return the correct matching search results.

Typo tolerance is set to 1, which means that search displays results that differ from the search term by 1 letter, or results that have 2 letters in a different order. The first 4 letters of a search term need to be entered correctly for typo tolerance to take effect.

The following fields support typo tolerance:

Resource type Fields supporting typo tolerance
Products
  • title
  • product_type
  • variants.title
  • vendor
Pages
  • author
  • title
Articles
  • author
  • title
Collections
  • title

Partial word matches

Predictive search supports partial word matches. This means that it suggests results even if the word you've entered is still incomplete. For example, if you enter sweate, then you might see a suggested search result for sweater.

Predictive search has the following limitations when it applies partial word matches:

  • If a search query has more than one term, then partial word matches are applied only to the last term in the query.
  • Partial word matches are applied only to the end of a search term. For example, if you enter book, then you won't see a suggested search result for ebook.
  • Partial word matches are supported only for themes using specific languages. For more details, refer to General limitations and requirements.

Predictive search uses a different search engine than storefront search. Because of this, it doesn't handle partial word matches in the same way. Although predictive search supports partial word matches, storefront search supports them only if the prefix option parameter is set to last.

General requirements and limitations

This section contains information about how predictive search is supported and any current limitations.

Supported languages

Predictive search is supported only for themes that use the following theme languages:

  • English
  • French
  • Spanish
  • Portuguese (Brazil)
  • German
  • Dutch
  • Italian
  • Japanese
  • Danish
  • Swedish
  • Portuguese (Portugal)
  • Finnish
  • Norwegian (Bokml)
  • Turkish
  • Romanian
  • Hungarian
  • Russian
  • Polish
  • Czech
  • Greek
  • Icelandic
  • Lithuanian
  • Slovenian
  • Slovak
  • Bulgarian
  • Vietnamese
  • Croatian
  • Indonesian
  • Latvian
  • Estonian
  • Serbian
  • Ukrainian
  • Catalan
  • Norwegian (Nynorsk)
  • Faroese
  • Portuguese
  • Albanian
  • Bosnian
  • Afrikaans
  • Macedonian
  • Armenian
  • Serbo-Croatian
  • Latin
  • Welsh
  • Gaelic
  • Moldovan

A script tag in the <head> section indicates whether predictive search is supported for the theme language: <script id="shopify-features"></script>. This script tag includes a JSON-encoded predictiveSearch key with a boolean value. When it's set to true, the theme language is supported, and predictive search is enabled. Otherwise, it's set to false.

Limitations

  • Individual products can't be excluded from predictive search results. If a product has been hidden from SEO by using the metafield object, then it won't appear in predictive search results. To learn more, see The metafield object.
  • The API returns no more than 10 product suggestions per request.