Autocomplete: Get Suggestions
curl --request GET \
--url 'https://app.uselayers.com/api/storefront/v1/search/complete?query={query}' \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>'import requests
url = "https://app.uselayers.com/api/storefront/v1/search/complete?query={query}"
headers = {
"X-Storefront-Access-Token": "<x-storefront-access-token>",
"Content-Type": "<content-type>",
"Accept": "<accept>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-Storefront-Access-Token': '<x-storefront-access-token>',
'Content-Type': '<content-type>',
Accept: '<accept>'
}
};
fetch('https://app.uselayers.com/api/storefront/v1/search/complete?query={query}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.uselayers.com/api/storefront/v1/search/complete?query={query}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: <accept>",
"Content-Type: <content-type>",
"X-Storefront-Access-Token: <x-storefront-access-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.uselayers.com/api/storefront/v1/search/complete?query={query}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Storefront-Access-Token", "<x-storefront-access-token>")
req.Header.Add("Content-Type", "<content-type>")
req.Header.Add("Accept", "<accept>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.uselayers.com/api/storefront/v1/search/complete?query={query}")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.uselayers.com/api/storefront/v1/search/complete?query={query}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Storefront-Access-Token"] = '<x-storefront-access-token>'
request["Content-Type"] = '<content-type>'
request["Accept"] = '<accept>'
response = http.request(request)
puts response.read_body{
"matchedQueries": [
"sup",
"supreme"
],
"originalQuery": "sup",
"normalizedQuery": "sup"
}
{
"matchedQueries": [
"support"
],
"originalQuery": "support",
"normalizedQuery": "support",
"_meta": {
"redirect": {
"url": "https://yourstore.com/pages/contact-us"
}
}
}
{
"matchedQueries": [
"summer dresses",
"linen shirts",
"white sneakers"
],
"originalQuery": null,
"normalizedQuery": null
}
Autocomplete
Autocomplete: Get Suggestions
Autocomplete API endpoint returning ranked search-query suggestions and top trending queries as shoppers type into your storefront search bar.
GET
/
search
/
complete?query=
{query}
Autocomplete: Get Suggestions
curl --request GET \
--url 'https://app.uselayers.com/api/storefront/v1/search/complete?query={query}' \
--header 'Accept: <accept>' \
--header 'Content-Type: <content-type>' \
--header 'X-Storefront-Access-Token: <x-storefront-access-token>'import requests
url = "https://app.uselayers.com/api/storefront/v1/search/complete?query={query}"
headers = {
"X-Storefront-Access-Token": "<x-storefront-access-token>",
"Content-Type": "<content-type>",
"Accept": "<accept>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-Storefront-Access-Token': '<x-storefront-access-token>',
'Content-Type': '<content-type>',
Accept: '<accept>'
}
};
fetch('https://app.uselayers.com/api/storefront/v1/search/complete?query={query}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.uselayers.com/api/storefront/v1/search/complete?query={query}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: <accept>",
"Content-Type: <content-type>",
"X-Storefront-Access-Token: <x-storefront-access-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.uselayers.com/api/storefront/v1/search/complete?query={query}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Storefront-Access-Token", "<x-storefront-access-token>")
req.Header.Add("Content-Type", "<content-type>")
req.Header.Add("Accept", "<accept>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.uselayers.com/api/storefront/v1/search/complete?query={query}")
.header("X-Storefront-Access-Token", "<x-storefront-access-token>")
.header("Content-Type", "<content-type>")
.header("Accept", "<accept>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.uselayers.com/api/storefront/v1/search/complete?query={query}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Storefront-Access-Token"] = '<x-storefront-access-token>'
request["Content-Type"] = '<content-type>'
request["Accept"] = '<accept>'
response = http.request(request)
puts response.read_body{
"matchedQueries": [
"sup",
"supreme"
],
"originalQuery": "sup",
"normalizedQuery": "sup"
}
{
"matchedQueries": [
"support"
],
"originalQuery": "support",
"normalizedQuery": "support",
"_meta": {
"redirect": {
"url": "https://yourstore.com/pages/contact-us"
}
}
}
{
"matchedQueries": [
"summer dresses",
"linen shirts",
"white sneakers"
],
"originalQuery": null,
"normalizedQuery": null
}
The Autocomplete endpoint returns ranked query-text suggestions for a partial search term. It does not return products, product previews, or images. Use the Search endpoint to fetch products for a chosen suggestion.
When no
query is provided, the endpoint returns the store’s top trending queries (subject to the same brand curation rules as live suggestions).
Authorization
string
required
Token-based authentication header in the form of
<YOUR_LAYERS_TOKEN>.Headers
string
default:"application/json"
required
string
default:"application/json"
required
Query parameters
string
The partial query you want suggestions for. Maximum 255 characters. Sanitized server-side; queries shorter than 2 characters after sanitization are treated as empty and return trending suggestions instead.
Response
string[]
Ranked array of suggestion strings. Prefix matches appear first, followed by non-prefix matches that clear the relevance threshold. Each string is the suggestion text the shopper should see: either the cluster’s canonical query or its curated display label when one is configured.
string | null
The
query value exactly as sent by the client. null when the request omits query or when the sanitized query is too short.string | null
The lowercased, trimmed form of
originalQuery used internally for matching. null when no query was effectively provided.object
Optional metadata. Present only when a semantic redirect matches the current query.
Semantic Redirects: When the autocomplete query matches a configured semantic redirect term, either exactly or semantically, the response includes a
_meta.redirect object with the redirect URL. This lets you redirect users directly from the typeahead experience before they submit a full search.Suggestion quality
Layers applies several techniques to keep autocomplete suggestions relevant and concise.Regional suggestions
Suggestion candidates can be scoped to the shopper’s country before matching runs. Layers resolves the country from IP-based geolocation and applies the store’s region mode:- Separate suggestions per region (default): shoppers in each country see suggestions built from that country’s own search activity. If a country doesn’t yet have enough curated search history to stand on its own, shoppers there receive the shared, store-wide suggestion set instead.
- One set of suggestions for all shoppers: every request returns the same store-wide suggestion set, regardless of the shopper’s location.
Brand curation
You can layer a natural-language brand prompt on top of the default suggestion pipeline. Layers uses the prompt — together with your store description — to suppress off-brand suggestions and rewrite display labels for customers. Suppressed clusters never appear inmatchedQueries, and curated clusters return their rewritten text in place of the canonical query. Matching against raw customer queries is unchanged. See Autocomplete curation for configuration details.
Stem deduplication
Autocomplete automatically collapses singular and plural variants of the same word into a single suggestion. For example, if your query data contains both “diamond” and “diamonds”, only the higher-scoring canonical form is returned. This also applies to other English stem variations like “berry” and “berries” or “long sleeve” and “long-sleeve”. Stem awareness extends to query matching as well. When you search for “diamonds”, autocomplete finds suggestions containing the singular “diamond” and vice versa. This means singular and plural queries produce identical suggestion lists, so your customers see the same results regardless of which form they type. When multiple suggestions share the same stem, the suggestion with the highest relevance score is kept. Shorter canonical forms (typically the singular) win ties, which keeps the suggestion list clean and predictable.Relevance gating
Suggestions that don’t closely match the query text are filtered out before results are returned. Prefix matches (where the query is the beginning of a suggestion) always pass through. Non-prefix matches must meet a minimum text-similarity threshold to appear. This prevents semantically distant suggestions from surfacing alongside direct matches.{
"matchedQueries": [
"sup",
"supreme"
],
"originalQuery": "sup",
"normalizedQuery": "sup"
}
{
"matchedQueries": [
"support"
],
"originalQuery": "support",
"normalizedQuery": "support",
"_meta": {
"redirect": {
"url": "https://yourstore.com/pages/contact-us"
}
}
}
{
"matchedQueries": [
"summer dresses",
"linen shirts",
"white sneakers"
],
"originalQuery": null,
"normalizedQuery": null
}
Was this page helpful?