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 |
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": {
"internalId": ["123456"],
"author": ["Pelle"]
}
},
// 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: December 8, 2020