Skip to content

Autocomplete

Autocomplete is a query to be used to retrieve search suggestions, product suggestions, and content item suggestions as the visitor types. All suggestions are returned with autocorrect automatically applied as well as supporting highlighting hints, compatible with any corrections.

A query can be sent on every key-press, but a debounce on 50 ms is recommended to avoid unnecessary requests while still creating an extremely snappy experience.

Request

Request method

GET or POST

Request URL

https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/autocomplete

Request parameters

Name Type Description Example
market string The visitor market identifier. Must match the corresponding market identifier in the data feed.
Required
UK
touchpoint string The vistor's touchpoint. Valid values are DESKTOP and MOBILE.
Required
DESKTOP
customerKey string A key that uniquely identifies the current visitor.
Using UUIDs as keys are recommended.
Required
0b05119e-eeb8-418a-bbfb-defa0dde417e
sessionKey string A unique key, identifying the session.
Using UUIDs as keys are recommended.
Required
0b05119e-eeb8-418a-bbfb-defa0dde417e
q string The visitor search query.
Required
sho
priceId string A custom price identifier. Must match supplied custom price identifiers in the data feed. EUR
notify boolean A boolean that can be used to disable notifications and behavioural registration for the query. false
viewId string A parameter that is used to show the page in either production or prewiew mode. Can be production or preview. Defaults to production if omitted in the query. For more information, see App Integration. production

Request headers

All request headers are optional, but recommended when eligible.

  • Content-Type - application/json. To prevent automatic browser preflight requests, text/plain is also supported.
  • Accept-Encoding - gzip. Allows responses to be compressed using Gzip.
  • User-Agent - User agent. Enables internal tracking.

Request body

The autocomplete page configuration supports being restricted through product filters and enriched with content.

Name Type Description
productFilter ProductFilter[ ] A filter, restricting the allowed products in the response.
contentLists ContentList[ ] A list of content lists to be included in the response. Amount of content items per list defaults to 3.

Request example

An autocomplete query example is demonstrated using cURL below.

#!/bin/bash
curl -i \
-H "Accept-Encoding: gzip" \
-H "User-Agent: {client user agent}" \
"https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/autocomplete?market=EU&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&q=shi"

Request example 2

An autocomplete query example using POST is demonstrated below.

#!/bin/bash
curl -i \
-X POST \
-T request-body.json \
-H "Content-Type: text/plain" \
-H "Accept-Encoding: gzip" \
-H "User-Agent: {client user agent}" \
"
https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/autocomplete?market=EU&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&q=shi"

request-body.json

{
  "contentLists": [
    {
      "id": "-",
      "contentFilter": {
        "type": ["article", "store"]
      },
      "limit": 5
    }
  ]
}

Response

Response headers

X-Response-Time

Response content-type

application/json

Response codes

Response Description
200 Query accepted, content flattened and serialised to JSON, see Response objects.
400 Invalid or missing arguments for this query.
404 End point is not valid.
503 Service unavailable, no products found in the cluster.
5xx Server error such as cluster unavailable or busy. The response body may contain more information about the error.

Response objects

Response example
{
    "productSuggestions": [
        {
            "products": [
                {
                    "key": "800291_1",
                    "ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvU0VBUkNIX0FTU0lTVEFOVC9QUk9EVUNUX1NVR0dFU1Q7Iztwcm9kdWN0X2tleTs4MDAyOTFfMTsjO09CSkVDVElWRSQ7IzsjOw",
                    "imageInfo": {
                        "effect": "GALLERY",
                        "images": [
                            {
                                "sources": [
                                    {
                                        "url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/800291_Tuxedo_Shirt_DC_HT_01_White_f_list.jpg",
                                        "width": 920
                                    },
                                    {
                                        "url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/800291_Tuxedo_Shirt_DC_HT_01_White_f.jpg",
                                        "width": 1667
                                    }
                                ]
                            },
                            {
                                "sources": [
                                    {
                                        "url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/800291_Tuxedo_Shirt_DC_HT_01_White_s_list.jpg",
                                        "width": 920
                                    },
                                    {
                                        "url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/800291_Tuxedo_Shirt_DC_HT_01_White_s.jpg",
                                        "width": 1667
                                    }
                                ]
                            }
                        ],
                        "thumbnail": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/800291_Tuxedo_Shirt_DC_HT_01_White_f_thumbnail.jpg"
                    },
                    "swatch": {
                        "type": "COLORS",
                        "colors": [
                            "#f6f6f8"
                        ]
                    },
                    "brand": "Gazelle",
                    "title": "Tuxedo Shirt DC HT",
                    "link": "/article/tuxedo-shirt-dc-ht?attr1_id=1",
                    "sellingPrice": {
                        "min": 159.0,
                        "max": 159.0
                    },
                    "listPrice": {
                        "min": 159.0,
                        "max": 159.0
                    },
                    "inStock": true,
                    "badges": {
                        "primary": [],
                        "secondary": [
                            {
                                "theme": "THEME_1",
                                "label": "Exclusive"
                            }
                        ]
                    },
                    "variants": [
                        {
                            "key": "8002911001137",
                            "ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvU0VBUkNIX0FTU0lTVEFOVC9QUk9EVUNUX1NVR0dFU1Q7Iztwcm9kdWN0X2tleTs4MDAyOTFfMTs4MDAyOTExMDAxMTM3OyM7IzsjOw",
                            "size": "37",
                            "inStock": true,
                            "link": "/article/tuxedo-shirt-dc-ht?attr1_id=1",
                            "listPrice": 159.0,
                            "sellingPrice": 159.0
                        }
                        // More variants
                    ]
                }
                // More products
            ],
            "key": "800291"
        }
        // More product groups
    ],
    "totalHits": 134,
    "phraseSuggestions": [
        {
            "highlighted": "{shi}rts",
            "q": "shirts"
        },
        {
            "highlighted": "{shi}rts new",
            "q": "shirts new"
        },
        {
            "highlighted": "{shi}rts men",
            "q": "shirts men"
        },
        {
            "highlighted": "{shi}rts women",
            "q": "shirts women"
        },
        {
            "highlighted": "{shi}rts blue",
            "q": "shirts blue"
        }
    ],
    "contentSuggestions": [
        {
            "title": "Shipping",
            "highlightedTitle": "{Shi}pping",
            "link": "/customer-services/shipping",
            "ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvU0VBUkNIX0FTU0lTVEFOVC9DT05URU5UX1NVR0dFU1Q7Iztjb250ZW50X3VybDsvY3VzdG9tZXItc2VydmljZXMvc2hpcHBpbmc7IzsjOyM7Izs"
        }
    ],
    "contentLists": [
        {
            "id": "-",
            "totalHits": 3,
            "items": [
                {
                    "key": "a1",
                    "type": "article",
                    "title": "How to wash shirts",
                    "link": "/wash-guide",
                    "ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
                    "releaseDate": "2019-10-01T00:00:00Z",
                    "description": "To wash or not to wash? And how?! Those are questions many shirt shoppers are asking these days.",
                    "image": {
                        "sources": [{"url": "img-w500.jpg", "width": 500}, {"url": "img-w1000.jpg", "width": 1000}]
                    },
                    "custom": {
                        "modifiedTime": [{"id": "2021-02-04", "label": "2021-02-04"}],
                        "author": [{"id": "John Doe", "label": "John Doe"}]
                    }
                },
                // Potentially more content items
                }
            ]
        },
        // Potentially more content lists
        }
    }
}

Autocomplete

Name Type Description
phraseSuggestions PhraseSuggestion[ ] A list of PhraseSuggestion, that matched the query.
productSuggestions ProductGroup[ ] A list of ProductGroup, that matched the query.
contentSuggestions ContentSuggestion[ ] A list of ContentSuggestion, that matched the query.
contentLists ContentList[ ] A list of lists of requested content, as specified in request body.
Empty unless specified in request body.
totalHits int The total number of ProductGroup[ ] that matched query.
redirectLink? string Redirect directly to a product page. Returned if the visitor should be redirected to a product page instead of search result.

Phrase suggestions

Name Type Description
highlighted string Matching phrase with highlight, e.g. {{jea}}ns. When implementing, always highlight the differences from the input.
q string Matching phrase, to be used as the query for search when clicked on by the visitor.

Content suggestions

Name Type Description
title string The title of the content page matching the query.
highlightedTitle string The matching content page title with highlight, e.g. {{Return}}s. When implementing, always highlight the differences from the input.
link string A link to the content page.
ticket string Use with notifications to notify visitor interaction.

Last update: June 18, 2021
×
Copyright

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE