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¶

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¶

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