Category Page and Landing Page¶
Category pages and generic landing pages are requested through the same end point, called landing-page. This end point caters for any page with faceted product listings, recommendation listings, or a combination of the two. It is suitable for the start page and intermediate category pages, as well as category pages, brand pages, and for example collection pages.
Inclusion of a primary product listing with facets, and which recommendation listings to include is configurable.
Request¶
Request method¶
GET or POST
Request URL¶
https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/landing-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 |
pageId | string | An ID uniquely identifying this page. For more information about pageId and how to select it, see Page IDs.Required | /women/shoes/loafers |
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. | 60 |
f.* | string | The applied Facet selection in the primary product listing. | f.price.max=350 |
sort | string | The applied Sort order in the primary product listing. | RELEVANCE |
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/plainis also supported.Accept-Encoding-gzip. Allows responses to be compressed using Gzip.User-Agent- User agent. Enables internal tracking.
Request body¶
The landing page can be configured to return additional recommendation listings and/or content listings. The main product listing can also be restricted through product filters. The landing page can also be configured to
| Name | Type | Description |
|---|---|---|
primaryList | PrimaryList | A primary listing to be included in the response, additionally supporting filter restrictions of the listing. I.e. a typical category product listing. |
recommendationLists | RecommendationList[ ] | A list of recommendation lists to be included in the response. |
navigation | {include: boolean} | An object with navigation options. Defaults to include: false. Set to include: true to return the navigation object (including breadcrumbs), i.e. when navigation is handled through eSales. |
contentLists | ContentList[ ] | A list of content lists to be included in the response. Amount of content items per list defaults to 10. |
Request example 1¶
A request example well suited for a typical category page is demonstrated using cURL 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/landing-page?market=EU&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&pageId=/women/shoes/loafers&limit=24"
request-body.json¶
{
"primaryList": {
"include": true
},
"navigation": {
"include": true
}
}
Request example 2¶
A request example suitable for e.g. a start page, with personal recommendations and top products on sale, is demonstrated using cURL 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/landing-page?market=EU&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&pageId=/home"
request-body.json¶
{
"recommendationLists": [
{
"id": "C1",
"limit": 4,
"algorithm": "PERSONAL"
},
{
"id": "C2",
"limit": 8,
"algorithm": "TOP_PRODUCTS",
"productFilter": {
"discount": {
"min": 1,
"max": 100
}
}
}
]
}
Request example 3¶
A request example suitable for e.g. a content page, with the specified content and some articles, is demonstrated using cURL 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/landing-page?market=EU&sessionKey=4b116e34-0a7a-ce5d-5591-75c62f231967&customerKey=4b116e34-0a7a-ce5d-5591-75c62f231967&touchpoint=DESKTOP&pageId=/home"
request-body.json¶
{
"contentLists": [
{
"id": "articles",
"contentFilter": {
"type": ["article"]
},
"limit": 5,
"algorithm": "NEWEST_CONTENT"
},
{
"id": "list-of-c1",
"contentFilter": {
"content_key": ["c1"]
}
}
]
}
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 1
{
"primaryList": {
"productGroups": [
{
"products": [
{
"key": "060175_93",
"ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvTkFWSUdBVElPTl9QQUdFL05BVklHQVRJT05fUkVTVUxUOyM7cHJvZHVjdF9rZXk7MDYwMTc1XzkzOyM7OyM7Izs",
"imageInfo": {
"effect": "GALLERY",
"images": [
{
"sources": [
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060175_Lady_Car_Shoes_21_Orange_b_list.jpg",
"width": 920
},
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060175_Lady_Car_Shoes_21_Orange_b.jpg",
"width": 1667
}
]
},
{
"sources": [
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060175_Lady_Car_Shoes_21_Orange_f_list.jpg",
"width": 920
},
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060175_Lady_Car_Shoes_21_Orange_f.jpg",
"width": 1667
}
]
}
],
"thumbnail": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/060175_Lady_Car_Shoes_21_Orange_b_thumbnail.jpg"
},
"swatch": {
"type": "COLORS",
"colors": [
"#d35c37",
"#b1afaf"
]
},
"brand": "DKNY",
"title": "Lady Car Shoe",
"link": "/article/lady-car-shoe_060175?attr1_id=93",
"sellingPrice": {
"min": 139.0,
"max": 139.0
},
"listPrice": {
"min": 139.0,
"max": 139.0
},
"inStock": true,
"badges": {
"primary": [],
"secondary": []
},
"variants": [
{
"key": "0601751021420_36",
"ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvTkFWSUdBVElPTl9QQUdFL05BVklHQVRJT05fUkVTVUxUOyM7cHJvZHVjdF9rZXk7MDYwMTc1XzkzOzA2MDE3NTEwMjE0MjBfMzY7IzsjOyM7",
"size": "36",
"inStock": false,
"link": "/article/lady-car-shoe_060175?attr1_id=93",
"listPrice": 139.0,
"sellingPrice": 139.0
}
// More variants
]
}
// More products
],
"key": "060175"
}
// More product groups
],
"totalHits": 4,
"facets": [
{
"values": [
{
"id": "Loafers",
"label": "Loafers",
"selected": false,
"count": 4
},
{
"id": "Shoes",
"label": "Shoes",
"selected": false,
"count": 4
}
],
"sort": "ALPHABETICAL",
"selectedCount": 0,
"id": "custom.category",
"label": "Category",
"type": "TEXT"
},
{
"sizeTypes": [
{
"label": "",
"formats": [
{
"values": [
{
"id": ";Numeric;36",
"label": "36",
"selected": false,
"count": 4
},
{
"id": ";Numeric;37",
"label": "37",
"selected": false,
"count": 4
},
{
"id": ";Numeric;38",
"label": "38",
"selected": false,
"count": 4
},
{
"id": ";Numeric;39",
"label": "39",
"selected": false,
"count": 4
},
{
"id": ";Numeric;40",
"label": "40",
"selected": false,
"count": 4
},
{
"id": ";Numeric;41",
"label": "41",
"selected": false,
"count": 4
},
{
"id": ";Numeric;42",
"label": "42",
"selected": false,
"count": 4
}
]
}
]
}
],
"selectedCount": 0,
"id": "size",
"label": "Size",
"type": "SIZE"
},
{
"min": 139.0,
"max": 139.0,
"id": "price",
"label": "Price",
"type": "RANGE"
},
{
"values": [
{
"color": "#212121",
"id": "BLACK",
"label": "Black",
"selected": false,
"count": 1
},
{
"color": "#9e9e9e",
"id": "GRAY",
"label": "Grey",
"selected": false,
"count": 1
},
{
"color": "#e67d9b",
"id": "PINK",
"label": "Pink",
"selected": false,
"count": 1
},
{
"color": "#ff8940",
"id": "ORANGE",
"label": "Orange",
"selected": false,
"count": 1
},
{
"color": "#3e905f",
"id": "GREEN",
"label": "Green",
"selected": false,
"count": 1
},
{
"id": "MULTI",
"label": "Multi coloured",
"selected": false,
"count": 2
}
],
"selectedCount": 6,
"id": "color",
"label": "Colour",
"type": "COLOR"
}
],
"sort": {
"selected": "NEWEST_FIRST",
"options": [
{
"id": "NEWEST_FIRST",
"label": "New"
},
{
"id": "RELEVANCE",
"label": "Relevance"
},
{
"id": "PRICE_DESCENDING",
"label": "Highest price"
},
{
"id": "PRICE_ASCENDING",
"label": "Lowest price"
}
]
}
},
"navigation": {
"tree": {
"type": "PRODUCT",
"path": "/",
"label": "All",
"count": 595,
"selected": true,
"expandable": true,
"children": [
{
"type": "PRODUCT",
"path": "/new-arrivals",
"label": "New arrivals",
"count": 137,
"selected": false,
"expandable": true,
"children": []
},
{
"type": "PRODUCT",
"path": "/women",
"label": "Women",
"count": 183,
"selected": true,
"expandable": true,
"children": [
{
"type": "PRODUCT",
"path": "/women/tops",
"label": "Tops",
"count": 70,
"selected": false,
"expandable": true,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/dresses",
"label": "Dresses",
"count": 11,
"selected": false,
"expandable": false,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/skirts",
"label": "Skirts",
"count": 7,
"selected": false,
"expandable": false,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/shorts",
"label": "Shorts",
"count": 6,
"selected": false,
"expandable": false,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/trousers",
"label": "Trousers",
"count": 31,
"selected": false,
"expandable": true,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/outerwear",
"label": "Outerwear",
"count": 10,
"selected": false,
"expandable": true,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/shoes",
"label": "Shoes",
"count": 8,
"selected": true,
"expandable": true,
"children": [
{
"type": "PRODUCT",
"path": "/women/shoes/loafers",
"label": "Loafers",
"count": 4,
"selected": true,
"expandable": false,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/shoes/sandals",
"label": "Sandals",
"count": 4,
"selected": false,
"expandable": false,
"children": []
}
]
},
{
"type": "PRODUCT",
"path": "/women/blazers",
"label": "Blazers",
"count": 4,
"selected": false,
"expandable": false,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/swimwear",
"label": "Swimwear",
"count": 6,
"selected": false,
"expandable": true,
"children": []
},
{
"type": "PRODUCT",
"path": "/women/accessories",
"label": "Accessories",
"count": 30,
"selected": false,
"expandable": true,
"children": []
}
]
},
{
"type": "PRODUCT",
"path": "/men",
"label": "Men",
"count": 412,
"selected": false,
"expandable": true,
"children": []
},
{
"type": "PRODUCT",
"path": "/sale",
"label": "Sale",
"count": 17,
"selected": false,
"expandable": true,
"children": []
}
]
},
"breadcrumbs": [
{
"path": "/",
"label": "All"
},
{
"path": "/women",
"label": "Women"
},
{
"path": "/women/shoes",
"label": "Shoes"
},
{
"path": "/women/shoes/loafers",
"label": "Loafers"
}
]
},
"recommendationLists": [],
"seo": {
"preamble": "Exclusive loafers for everyday use",
"metaDescription": "Exclusive loafers for everyday use",
"pageTitle": "Loafers",
"canonicalPath": "/women/shoes/loafers"
}
}
Response example 2
{
"recommendationLists": [
{
"id": "C1",
"visualization": "GRID",
"visible": true,
"productGroups": [
{
"products": [
{
"key": "200789_65",
"ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvTEFORElOR19QQUdFL1JFQ19MSVNUL0MxOyM7cHJvZHVjdF9rZXk7MjAwNzg5XzY1OyM7T0JKRUNUSVZFJDsjOyM7",
"imageInfo": {
"thumbnail": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/200789_John_Minicheck_Suit_Blazer_80_Brown_f_thumbnail.jpg",
"effect": "GALLERY",
"images": [
{
"sources": [
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/200789_John_Minicheck_Suit_Blazer_80_Brown_f_list.jpg",
"width": 920
},
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/200789_John_Minicheck_Suit_Blazer_80_Brown_f.jpg",
"width": 1667
}
]
},
{
"sources": [
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/200789_John_Minicheck_Suit_Blazer_80_Brown_s_list.jpg",
"width": 920
},
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/200789_John_Minicheck_Suit_Blazer_80_Brown_s.jpg",
"width": 1667
}
]
}
]
},
"swatch": {
"type": "COLORS",
"colors": [
"#635147"
]
},
"brand": "Lyle & Scott",
"title": "John Minicheck Suit Blazer",
"link": "/article/john-minicheck-suit-blazer?attr1_id=65",
"sellingPrice": {
"min": 549.0,
"max": 549.0
},
"listPrice": {
"min": 549.0,
"max": 549.0
},
"inStock": true,
"badges": {
"primary": [
{
"style": "NEW",
"label": "New"
}
],
"secondary": [
{
"style": "THEME_1",
"label": "Exclusive"
}
]
},
"variants": [
{
"key": "2007891080048",
"ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvTEFORElOR19QQUdFL1JFQ19MSVNUL0MxOyM7cHJvZHVjdF9rZXk7MjAwNzg5XzY1OzIwMDc4OTEwODAwNDg7IzsjOyM7",
"size": "48",
"inStock": true,
"link": "/article/john-minicheck-suit-blazer?attr1_id=65",
"listPrice": 549.0,
"sellingPrice": 549.0
},
// More variants
]
},
// More products in group
],
"key": "200789"
},
// More product groups
],
"algorithm": "PERSONAL"
},
{
"id": "C2",
"visualization": "GRID",
"visible": true,
"productGroups": [
{
"products": [
{
"key": "750139_93",
"ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvTEFORElOR19QQUdFL1JFQ19MSVNUL0MyOyM7cHJvZHVjdF9rZXk7NzUwMTM5XzkzOyM7T0JKRUNUSVZFJDsjOyM7",
"imageInfo": {
"thumbnail": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/750139_Lt_Twill_Chino_Shorts_21_Orange_f_thumbnail.jpg",
"effect": "GALLERY",
"images": [
{
"sources": [
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/750139_Lt_Twill_Chino_Shorts_21_Orange_f_list.jpg",
"width": 920
},
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/750139_Lt_Twill_Chino_Shorts_21_Orange_f.jpg",
"width": 1667
}
]
},
{
"sources": [
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/750139_Lt_Twill_Chino_Shorts_21_Orange_b_list.jpg",
"width": 920
},
{
"url": "https://apptus-demo-images.s3.eu-central-1.amazonaws.com/img2020-04/750139_Lt_Twill_Chino_Shorts_21_Orange_b.jpg",
"width": 1667
}
]
}
]
},
"swatch": {
"type": "COLORS",
"colors": [
"#e99655"
]
},
"brand": "Adidas",
"title": "Lt Twill Chino Shorts",
"link": "/article/lt-twill-chino-shorts_750139?attr1_id=93",
"sellingPrice": {
"min": 69.3,
"max": 69.3
},
"listPrice": {
"min": 99.0,
"max": 99.0
},
"inStock": true,
"badges": {
"primary": [
{
"style": "DISCOUNT",
"label": "-30%"
}
],
"secondary": []
},
"variants": [
{
"key": "7501391021281",
"ticket": "Oy9mYXNoaW9uL0RFU0tUT1AvTEFORElOR19QQUdFL1JFQ19MSVNUL0MyOyM7cHJvZHVjdF9rZXk7NzUwMTM5XzkzOzc1MDEzOTEwMjEyODE7IzsjOyM7",
"size": "28",
"inStock": true,
"link": "/article/lt-twill-chino-shorts_750139?attr1_id=93",
"listPrice": 99.0,
"sellingPrice": 69.3
},
// More variants
]
},
// More products
],
"key": "750139"
},
// More product groups
],
"algorithm": "TOP_PRODUCTS"
}
]
}
Response example 3
{
"contentLists": [
{
"id": "articles",
"totalHits": 2,
"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 |
|---|---|---|
seo | SearchEngineOptimization[ ] | SEO information in accordance to the set up for the current page in the Experience app. |
recommendationLists | RecommendationList[ ] | A list of requested recommendation lists, as specified in the request body. Empty if none are specified in the request body. |
primaryList? | PrimaryList[ ] | A faceted product list with the assortment for the current page. Omitted unless specified in the request body. |
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. |
SEO¶
| Name | Type | Description |
|---|---|---|
preamble | string | Preamble text for the current category. Undefined if not configured for the current page. |
metaDescription | string | Description for the current category, use with: <meta type="description" content="{VALUE}">Undefined if not configured for the current page. |
pageTitle | string | Title for the current category, use with: <title>{VALUE}</title>Undefined if not configured for the current page. |
canonicalPath | string | Preferred URL for the current category, use with <link rel="canonical" href="{VALUE}">Undefined if not configured for the current page. |
Last update: May 28, 2021