Query parameters¶
Each page type has a set of applicable query parameters, found in the specification for each page type. The query parameters which apply to multiple pages, are detailed and listed in this section.
Base query parameters¶
Base query parameters apply to all pages. Those which are mandatory must be supplied for all requests, while optional ones are likely to be either be supplied in an equivalent manner for all page types or not at all.
Mandatory parameters¶
| Name | Type | Description | Example |
|---|---|---|---|
market | string | The visitor market. Must match the corresponding market identifier in the data feed. | UK |
touchpoint | string | The visitor's touchpoint. Valid values are DESKTOP and MOBILE. | DESKTOP |
customerKey | string | A key that uniquely identifies the current visitor. Using UUIDs as keys are recommended. | 0b05119e-eeb8-418a-bbfb-defa0dde417e |
sessionKey | string | A unique key, identifying the session. Using UUIDs as keys are recommended. | 0b05119e-eeb8-418a-bbfb-defa0dde417e |
Correct usage of the customer and session keys are essential for the behavioural data to be analysed correctly. A session starts when a visitor arrives at a site, and is identified through a unique sessionKey. The same sessionKey must be used though out the visit. For more information about customer keys, see Visitor identification.
Optional parameters¶
| Name | Type | Description | Example |
|---|---|---|---|
priceId | string | A custom price identifier. Must match supplied custom price identifiers in the data feed. | EUR |
notify | boolean | Turns off notifications and behavioural registration for the query. | false |
Price ID¶
When supplying a price ID to a request, the selling_price and list_price property of all products will be provided as the price in the data feed for that price ID. Sorting, faceting, and filtering on price will also be based on prices with the specified identifier.
Notify¶
The notify parameter should always be enabled in production for visitor facing parts of the e-commerce site. However, if any query is used for other purposes such as internal administrative tools or if a load test is run on the production environment with simulated data, ensure that notify=false is applied. This will prevent tests and internal tools to cause noise in statistics as well as erroneous behaviour analysis.
Note that this is not an issue for small scale testing, but rather something to consider when lots of non-visitor generated traffic is expected.
Facet selections¶
Facet selections are used for visitor facing product list filters. As opposed to product filters, facets are to be visualized and applicable and reversible by the visitors. All applicable facets are part of the response for Primary Listings. Each facet have an id, and should be provided along with the selected values as query parameters, when selected by the visitors.
Value facet syntax¶
Applicable for Text, Colour and Size Facets. All facet ids and value ids are found in the response for each facet. Multiple values are provided with a pipe, |, as a separator.
f.[id]=[value1.id]|[value2.id]
Range facet syntax¶
Range Facets are provided with min and max as suffix to the facetId with values for the desired range. Both min and max are inclusive and default to 0 and the maximum eligible value respectively.
f.[id].min=[min]&f.[id].max=[max]`
Request example¶
The following example illustrates a category page request with a brand, a season (custom attribute), and a price range selected as facets. Other request parameters have been omitted for brevity.
https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/category-page?
f.brand=adidas&f.custom.season=winter|spring&f.price.min=500&f.price.max=2500
Page IDs¶
For landing pages and category pages, unique page identifiers must be provided. Page identifiers will be visible and used to distinguish between pages in the eSales Apps, where merchandisers are provided with control of listings for each individual page.
For pages on the site, page paths should be used.
/women/dresses
For external requests, an identifier understood by merchandisers should be used.
mms-campaign-S2020
Sort orders¶
The sort parameter determines the applied sort order of the listing. All eligible sort orders are found in the Primary Listing response. Sort orders are sent as a query parameter with the id as the value which is one of the listed Sort types, sort=[id].
Request example¶
The following example illustrates a category page request with the sort order NEWEST_FIRST applied. Other request parameters have been omitted for brevity.
https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/category-page?sort=NEWEST_FIRST