Predictive Search API reference

The Predictive Search API can be used to display predictive search results for products, collections, pages, and articles.

To learn how to use predictive search in a theme, refer to Add predictive search to your theme.

GET /search/suggest.json

The following example request retrieves predictive results for a specified search query:

Query parameters

Query parameter Required Description
q Yes The search query.
resources Yes

Requests resources results for the given query based on the following attributes:

  • type
  • limit
  • options
type Yes

Specifies the type of results requested.

The following are the accepted values, which can be combined in a comma-separated list:

  • product
  • page
  • article
  • collection

For example, product,collection,article.

limit No

Limits the number of results returned per type.

The value can range from 1 to 10, and the default is 10.

options No

Specifies options for the requested resources based on the following attributes:

  • unavailable_products
  • fields
unavailable_products No

Specifies whether to display results for unavailable products.

The following are the accepted values:

  • show: Show unavailable products.
  • hide: Hide unavailable products.
  • last: Show unavailable products below other matching results.

The default value is last.

fields No

Specifies the list of resource fields to search.

The following are the accepted values:

  • author
  • body
  • product_type
  • tag
  • title
  • variants.barcode
  • variants.sku
  • variants.title
  • vendor

The default fields searched on are title, product_type, variants.title, and vendor. For the best search experience, you should search on the default field set, or as few fields as possible.

Resources response

The following example is a response to a successful request to the /search/suggest.json endpoint, which contains resource objects associated with the specified query:

Error responses

When a request to the /search/suggest.json endpoint is unsuccessful, one of the following error responses is returned:

Any other errors not listed will return a 5xx status code.

Invalid parameter error

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.

Expectation failed

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

Too many requests

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

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

GET /search/suggest

The following example request retrieves the HTML from a section rendered with the predictive results for a specified search query.

Query parameters

Query parameter Required Description
q Yes The search query.
resources Yes

Requests resources results for the given query based on the following attributes:

  • type
  • limit
  • options
type Yes

Specifies the type of results requested.

The following are the accepted values, which can be combined in a comma-separated list:

  • product
  • page
  • article
  • collection

For example, product,collection,article.

limit No

Limits the number of results returned per type.

The value can range from 1 to 10, and the default is 10.

options No

Specifies options for the requested resources based on the following attributes:

  • unavailable_products
  • fields
unavailable_products No

Specifies whether to display results for unavailable products.

The following are the accepted values:

  • show: Show unavailable products.
  • hide: Hide unavailable products.
  • last: Show unavailable products below other matching results.

The default value is last.

fields No

Specifies the list of resource fields to search.

The following are the accepted values:

  • author
  • body
  • product_type
  • tag
  • title
  • variants.barcode
  • variants.sku
  • variants.title
  • vendor

The default fields searched on are title, product_type, variants.title, and vendor. For the best search experience, you should search on the default field set, or as few fields as possible.

section_id Yes The unique section ID of the section file that you want render with the predictive search query.

Section response

The response to a successful request to the /search/suggest endpoint.

The section response contains the HTML of the provided section rendered with the predictive_search object containing the results of the specified query.

For example, the following section would generate the following section response:

Error responses

When a request to the /search/suggest endpoint is unsuccessful, one of the following error status codes is returned:

Status code Description
404 Section not found - The provided section ID wasn't found in the theme.
417 Expectation failed - The theme isn't using one of the supported languages.
422 Invalid parameter error - The value used for a query parameter was invalid.
429 Too many requests - The request throttle limit has been exceeded.

You can output the response text to get more details about an error. Refer to the example request using Fetch to learn more.

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 Requirements and limitations.

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.

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
  • 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 predictive suggestions per request type.