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 |
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/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": {
"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: May 28, 2021