Skip to content

Search Page

The search page query is intended to be used on the search page. A search page query will return a search result product listing with associated facets, navigation, applicable sort orders, and a result count.

Request

Request method

GET or POST

Request URL

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

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 visitor'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 executed search query.
Required
shoes
origin string The search origin of the search phrase. Defaults to ORGANIC.
Recommended
AUTO_COMPLETE
limit int The number of product groups to list. Defaults to 60 if omitted in the query. 60
skip int The number of product groups to skip. Used for pagination, defaults to 0 if omitted in the query. 48
selectedCategory string The selected category in the navigation. Use the path from selected node in the navigation tree. /women/dresses
f.* string The applied Facet selection in the search result f.price.max=350
sort string The applied Sort order in the search result. Strongly recommended to omit for initial searches. Only recommended for explicit visitor interaction after initial searches. PRICE_ASCENDING
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

Search origin

To correctly track and analyse search behaviour, searches that originate from autocomplete suggestions, triggered through did-you-mean, or are actual organic searches are differentiated. Supplying this for non-organic searches is important for optimal performance and accurate statistics.

Name Description
ORGANIC The search was organic, e.g. the phrase was typed and executed by a visitor without any assistance or suggestion interaction.
PHRASE_SUGGEST The search phrase originated from a phrase suggestion in search.
DID_YOU_MEAN The search phrase originated from a did-you-mean suggestion in search.
UNDO_AUTO_CORRECT A search phrase which forcibly omits autocorrect. Used when visitors have phrases autocorrected, and are presented with the option to redo the search using the original phrase.

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 search result of the search page can be configured to be restricted through product filters and enriched with content.

Name Type Description
primaryList PrimaryList A configuration object allowing filter restrictions of the primary listing, i.e. the search results.
navigation {
include: boolean
}
An object with navigation options. Defaults to include: false. Set to include: true to return the navigation object, i.e. when navigation is handled through eSales.
contentLists ContentList[ ] A list of content lists to be included in the response. The amount of content items per list defaults to 5.

Request example

A search page 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/search-page?market=EU&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&q=shos&limit=24"

Request example 2

A search page 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/search-page?market=EU&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&q=shoes&limit=24"

request-body.json

{
  "primaryList": {
    "productFilter": {
      "brand": "Calvin Klein"
    }
  },
  "navigation": {
    "include": true
  },
  "contentLists": [
    {
      "id": "-",
      "contentFilter": {
        "type": ["article", "store"]
      },
      "limit": 3
    }
  ]
}

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

JSON
{
    "q": "shos",
    "autoCorrect": {
        "q": "shoes",
        "originalTotalHits": 0
    },
    "didYouMean": [],
    "primaryList": {
        "productGroups": [
            {
                "products": [
                    {
                        "key": "060194_7",
                        "ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvU0VBUkNIX1BBR0UvU0VBUkNIX1JFU1VMVDsjO3Byb2R1Y3Rfa2V5OzA2MDE5NF83OyM7T0JKRUNUSVZFJDsjOyM7",
                        "imageInfo": {
                            "thumbnail": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060194_Elaine_Sandal_05_Khaki_f_thumbnail.jpg",
                            "effect": "GALLERY",
                            "images": [
                                {
                                    "sources": [
                                        {
                                            "url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060194_Elaine_Sandal_05_Khaki_f_list.jpg",
                                            "width": 920
                                        },
                                        {
                                            "url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060194_Elaine_Sandal_05_Khaki_f.jpg",
                                            "width": 1667
                                        }
                                    ]
                                },
                                {
                                    "sources": [
                                        {
                                            "url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060194_Elaine_Sandal_05_Khaki_b_list.jpg",
                                            "width": 920
                                        },
                                        {
                                            "url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060194_Elaine_Sandal_05_Khaki_b.jpg",
                                            "width": 1667
                                        }
                                    ]
                                }
                            ]
                        },
                        "swatch": {
                            "type": "COLORS",
                            "colors": [
                                "#d9c19d",
                                "#7e5f40"
                            ]
                        },
                        "brand": "Fila",
                        "title": "Elaine Sandal",
                        "link": "/article/elaine-sandal?attr1_id=7",
                        "sellingPrice": {
                            "min": 149.0,
                            "max": 149.0
                        },
                        "listPrice": {
                            "min": 149.0,
                            "max": 149.0
                        },
                        "inStock": true,
                        "badges": {
                            "primary": [
                                {
                                    "style": "NEW",
                                    "label": "New"
                                }
                            ],
                            "secondary": []
                        },
                        "variants": [
                            {
                                "key": "0601941005360",
                                "ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvU0VBUkNIX1BBR0UvU0VBUkNIX1JFU1VMVDsjO3Byb2R1Y3Rfa2V5OzA2MDE5NF83OzA2MDE5NDEwMDUzNjA7IzsjOyM7",
                                "size": "36",
                                "inStock": true,
                                "link": "/article/elaine-sandal?attr1_id=7",
                                "listPrice": 149.0,
                                "sellingPrice": 149.0
                            },
                           // More variants
                        ]
                    },

                    // More products
                ],
                "key": "060194"
            },

            // More product groups
        ],
        "totalHits": 12,
        "facets": [
            {
                "values": [
                    {
                        "id": "Loafers",
                        "label": "Loafers",
                        "selected": false,
                        "count": 8
                    },
                    {
                        "id": "Sandals",
                        "label": "Sandals",
                        "selected": false,
                        "count": 4
                    },
                    {
                        "id": "Shoes",
                        "label": "Shoes",
                        "selected": false,
                        "count": 12
                    }
                ],
                "sort": "ALPHABETICAL",
                "selectedCount": 0,
                "id": "custom.category",
                "label": "Category",
                "type": "TEXT"
            },
            {
                "sizeTypes": [
                    {
                        "label": "Available sizes",
                        "formats": [
                            {
                                "format": "custom.EU",
                                "values": [
                                    {
                                        "id": ";custom.EU;36",
                                        "label": "36",
                                        "selected": false,
                                        "count": 8
                                    },
                                    {
                                        "id": ";custom.EU;37",
                                        "label": "37",
                                        "selected": false,
                                        "count": 8
                                    },
                                    {
                                        "id": ";custom.EU;38",
                                        "label": "38",
                                        "selected": false,
                                        "count": 8
                                    },
                                    {
                                        "id": ";custom.EU;39",
                                        "label": "39",
                                        "selected": false,
                                        "count": 8
                                    },
                                    {
                                        "id": ";custom.EU;40",
                                        "label": "40",
                                        "selected": false,
                                        "count": 12
                                    },
                                    {
                                        "id": ";custom.EU;41",
                                        "label": "41",
                                        "selected": false,
                                        "count": 12
                                    },
                                    {
                                        "id": ";custom.EU;42",
                                        "label": "42",
                                        "selected": false,
                                        "count": 12
                                    },
                                    {
                                        "id": ";custom.EU;43",
                                        "label": "43",
                                        "selected": false,
                                        "count": 4
                                    },
                                    {
                                        "id": ";custom.EU;44",
                                        "label": "44",
                                        "selected": false,
                                        "count": 4
                                    },
                                    {
                                        "id": ";custom.EU;45",
                                        "label": "45",
                                        "selected": false,
                                        "count": 4
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "selectedCount": 0,
                "id": "size",
                "label": "Size",
                "type": "SIZE"
            },
            {
                "min": 129.0,
                "max": 225.53,
                "id": "selling_price",
                "label": "Price",
                "type": "RANGE"
            },
            {
                "values": [
                    {
                        "color": "#212121",
                        "id": "BLACK",
                        "label": "Black",
                        "selected": false,
                        "count": 3
                    },
                    {
                        "color": "#9e9e9e",
                        "id": "GRAY",
                        "label": "Grey",
                        "selected": false,
                        "count": 5
                    },
                    {
                        "color": "#d4be94",
                        "id": "BEIGE",
                        "label": "Beige",
                        "selected": false,
                        "count": 3
                    },
                    {
                        "color": "#6b4122",
                        "id": "BROWN",
                        "label": "Brown",
                        "selected": false,
                        "count": 3
                    },
                    {
                        "color": "#e67d9b",
                        "id": "PINK",
                        "label": "Pink",
                        "selected": false,
                        "count": 1
                    },
                    {
                        "color": "#ff8940",
                        "id": "ORANGE",
                        "label": "Orange",
                        "selected": false,
                        "count": 1
                    },
                    {
                        "color": "#ffdab9",
                        "id": "PEACH",
                        "label": "Peach",
                        "selected": false,
                        "count": 1
                    },
                    {
                        "color": "#ffe44d",
                        "id": "YELLOW",
                        "label": "Yellow",
                        "selected": false,
                        "count": 1
                    },
                    {
                        "color": "#3e905f",
                        "id": "GREEN",
                        "label": "Green",
                        "selected": false,
                        "count": 1
                    },
                    {
                        "id": "MULTI",
                        "label": "Multi coloured",
                        "selected": false,
                        "count": 6
                    }
                ],
                "selectedCount": 10,
                "id": "color_code",
                "label": "Colour",
                "type": "COLOR"
            },
            {
                "values": [
                    {
                        "id": "Bardot",
                        "label": "Bardot",
                        "selected": false,
                        "count": 2
                    },
                    {
                        "id": "Chanel",
                        "label": "Chanel",
                        "selected": false,
                        "count": 2
                    },
                    {
                        "id": "Cheap Monday",
                        "label": "Cheap Monday",
                        "selected": false,
                        "count": 2
                    },
                    {
                        "id": "DKNY",
                        "label": "DKNY",
                        "selected": false,
                        "count": 4
                    },
                    {
                        "id": "Fila",
                        "label": "Fila",
                        "selected": false,
                        "count": 2
                    }
                ],
                "sort": "ALPHABETICAL",
                "selectedCount": 0,
                "id": "brand",
                "label": "Brand",
                "type": "TEXT"
            }
        ],
        "sort": {
            "selected": "RELEVANCE",
            "options": [
                {
                    "id": "RELEVANCE",
                    "label": "Relevance"
                },
                {
                    "id": "NEWEST_FIRST",
                    "label": "New"
                },
                {
                    "id": "PRICE_DESCENDING",
                    "label": "Highest price"
                },
                {
                    "id": "PRICE_ASCENDING",
                    "label": "Lowest price"
                },
                {
                    "id": "DISCOUNT",
                    "label": "Discount"
                }
            ]
        }
    },
    "contentLists": [
        {
            "id": "content-hits",
            "totalHits": 3,
            "items": [
                {
                    "key": "a1",
                    "type": "article",
                    "title": "How to wash jeans",
                    "link": "/wash-guide",
                    "ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
                    "releaseDate": "2019-10-01T00:00:00Z",
                    "description": "To wash or not to wash? And how?! Those are questions many jeans 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
        }
    }
}
Name Type Description
primaryList PrimaryList A faceted product list with the search result.
q string The search query used for the current result. May be corrected and differ from the requested query.
didYouMean DidYouMean[ ] A list of did-you-mean suggestions.
autoCorrect? AutoCorrect Information about applied auto corrections to the search phrase.
Omitted if no correction was made.
navigation? NavigationNode The root node of the navigation structure.
Omitted unless specified in the request body.
contentLists ContentList[ ] A list of lists of requested content, as specified in request body.
Empty unless specified in the request body.

Last update: June 29, 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