Search Page¶
The search page query is intended to be used on the search page. A search page query will return a the 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 |
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/plainis 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": {
"internalId": ["123456"],
"author": ["Pelle"]
}
},
// 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: December 8, 2020