Skip to content

Content Search Page

https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/content-search-page

GET

The content search page query is intended to be used on a separate part of a site, such as an FAQ or a customer service section. A content search page query will return a search result content listing with applicable sort orders and total hits.

Request

Header parameters

Name Description Example
Accept-Encoding Allows responses to be compressed using Gzip. gzip

Query parameters

Name Description Example
customerKey
Required 		A key that uniquely identifies the current visitor.
Using UUIDs as keys are recommended.		 0b05119e-eeb8-418a-bbfb-defa0dde417e
locale
Required 		The visitor locale. Must match an available locale identifier on the current market in the data feed.
market
Required 		The visitor market identifier. Must match the corresponding market identifier in the data feed. UK
q
Required 		The executed search query. shipping
sessionKey
Required 		A unique key, identifying the session.
Using UUIDs as keys are recommended.		 0b05119e-eeb8-418a-bbfb-defa0dde417e
touchpoint
Required 		The visitor's touchpoint. Supported values: DESKTOP, MOBILE. DESKTOP
limit The number of content items to list. Defaults to 60 if omitted in the query, the min value is 1 and the max value is 600. 10
notify A boolean that can be used to disable notifications and behavioural registration for the query. false
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. Supported values: ORGANIC, DID_YOU_MEAN, UNDO_AUTO_CORRECT, PHRASE_SUGGEST, RELATED_SEARCHES, RECENT_SEARCH. ORGANIC
skip The number of content items to skip. Used for pagination, defaults to 0 if omitted in the query. 10
sort The applied Sort order in the search result. Strongly recommended to omit for initial searches. Only recommended for explicit visitor interaction after initial searches. Supported values: RELEVANCE, NEWEST_FIRST. NEWEST_FIRST
viewId A parameter that is used to show the page in either production or preview mode. Can be production or preview. Defaults to production if omitted in the query. For more information, see App Integration. Supported values: PRODUCTION, PREVIEW. production 
curl -i \
-X GET \
-H 'Accept-Encoding: gzip' \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/content-search-page?customerKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&locale=locale&market=UK&q=shipping&sessionKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&touchpoint=DESKTOP&limit=10&notify=false&origin=ORGANIC&skip=10&sort=NEWEST_FIRST&viewId=production"

Response

Response codes

Status Description
200 Query accepted, content flattened and serialised to JSON.
400 Invalid or missing required arguments.
404 Endpoint is not valid.
503 Service unavailable, no products found in the cluster.
500 Server error such as cluster unavailable or busy. The response body may contain more information about the error.

Response headers

Name Type Description Example
X-Response-Time integer Response time in milliseconds (ms) 65

Response body

Example
application/json;charset=utf-8
{
  "autoCorrect" : {
    "originalTotalHits" : 5,
    "q" : "Jeans"
  },
  "didYouMean" : [ {
    "q" : "shoes"
  } ],
  "primaryList" : {
    "items" : [ {
      "custom" : {
        "tags" : [ {
          "id" : "78",
          "label" : "Guide"
        }, {
          "id" : "223",
          "label" : "Jeans"
        } ]
      },
      "description" : "To wash or not to wash? And how?! Those are questions jeans shoppers are asking.",
      "image" : {
        "alt" : "A woman wearing a white t-shirt",
        "caption" : "The model is 176 cm tall and is wearing size S",
        "custom" : { },
        "sources" : [ {
          "url" : "https://cdn.example.com/img/j12_prod.jpg",
          "height" : 820,
          "width" : 420
        } ]
      },
      "key" : "wash_care",
      "link" : "/wash-guide",
      "releaseDate" : "2021-10-01T00:00:00Z",
      "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
      "title" : "How to wash jeans",
      "type" : "article"
    } ],
    "sort" : {
      "options" : [ {
        "id" : "RELEVANCE",
        "label" : "Relevance"
      } ],
      "selected" : "RELEVANCE"
    },
    "totalHits" : 0
  },
  "q" : "Jean"
}
Schema

ContentSearchPageResult

The object representation of the content search page result.

Name Type Description Example
autoCorrect AutoCorrect Information about applied auto corrections to the search phrase. Omitted if no correction was made.
didYouMean DidYouMean[] A list of did-you-mean suggestions
primaryList PrimaryContentList A content list with the search result.
q string The search query used for the current result. May be corrected and differ from the requested query. "Jean"

POST

The content search page query is intended to be used on a separate part of a site, such as an FAQ or a customer service section. A content search page query will return a search result content listing with applicable sort orders and total hits.

Request

Header parameters

Name Description Example
Accept-Encoding Allows responses to be compressed using Gzip. gzip

Query parameters

Name Description Example
customerKey
Required 		A key that uniquely identifies the current visitor.
Using UUIDs as keys are recommended.		 0b05119e-eeb8-418a-bbfb-defa0dde417e
locale
Required 		The visitor locale. Must match an available locale identifier on the current market in the data feed.
market
Required 		The visitor market identifier. Must match the corresponding market identifier in the data feed. UK
q
Required 		The executed search query. shipping
sessionKey
Required 		A unique key, identifying the session.
Using UUIDs as keys are recommended.		 0b05119e-eeb8-418a-bbfb-defa0dde417e
touchpoint
Required 		The visitor's touchpoint. Supported values: DESKTOP, MOBILE. DESKTOP
limit The number of content items to list. Defaults to 60 if omitted in the query, the min value is 1 and the max value is 600. 10
notify A boolean that can be used to disable notifications and behavioural registration for the query. false
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. Supported values: ORGANIC, DID_YOU_MEAN, UNDO_AUTO_CORRECT, PHRASE_SUGGEST, RELATED_SEARCHES, RECENT_SEARCH. ORGANIC
skip The number of content items to skip. Used for pagination, defaults to 0 if omitted in the query. 10
sort The applied Sort order in the search result. Strongly recommended to omit for initial searches. Only recommended for explicit visitor interaction after initial searches. Supported values: RELEVANCE, NEWEST_FIRST. NEWEST_FIRST
viewId A parameter that is used to show the page in either production or preview mode. Can be production or preview. Defaults to production if omitted in the query. For more information, see App Integration. Supported values: PRODUCTION, PREVIEW. production

Supported Content-Type

  • application/json;charset=utf-8
  • text/plain;charset=utf-8

Request body

Example
application/json;charset=utf-8
{
  "primaryList" : {
    "contentFilter" : {
      "content_key" : [ [ "a1", "d2" ] ],
      "custom.ATTRIBUTE" : "abc123",
      "type" : [ [ "article", "designer" ] ]
    }
  }
}
Schema

ContentSearchPageRequestSettings

A configuration object allowing filter restrictions of the primary listing, i.e. the search results.

Name Type Description Example
primaryList PrimaryContentListSettings A configuration object allowing filter restrictions of the primary listing, i.e. the search results. 
curl -i \
-X POST \
-H 'Accept-Encoding: gzip' \
-H 'Content-Type: application/json;charset=utf-8' \
"https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/content-search-page?customerKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&locale=locale&market=UK&q=shipping&sessionKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&touchpoint=DESKTOP&limit=10&notify=false&origin=ORGANIC&skip=10&sort=NEWEST_FIRST&viewId=production" \
-T request-body.file

Response

Response codes

Status Description
200 Query accepted, content flattened and serialised to JSON.
400 Invalid or missing required arguments.
404 Endpoint is not valid.
503 Service unavailable, no products found in the cluster.
500 Server error such as cluster unavailable or busy. The response body may contain more information about the error.

Response headers

Name Type Description Example
X-Response-Time integer Response time in milliseconds (ms) 65

Response body

Example
application/json;charset=utf-8
{
  "autoCorrect" : {
    "originalTotalHits" : 5,
    "q" : "Jeans"
  },
  "didYouMean" : [ {
    "q" : "shoes"
  } ],
  "primaryList" : {
    "items" : [ {
      "custom" : {
        "tags" : [ {
          "id" : "78",
          "label" : "Guide"
        }, {
          "id" : "223",
          "label" : "Jeans"
        } ]
      },
      "description" : "To wash or not to wash? And how?! Those are questions jeans shoppers are asking.",
      "image" : {
        "alt" : "A woman wearing a white t-shirt",
        "caption" : "The model is 176 cm tall and is wearing size S",
        "custom" : { },
        "sources" : [ {
          "url" : "https://cdn.example.com/img/j12_prod.jpg",
          "height" : 820,
          "width" : 420
        } ]
      },
      "key" : "wash_care",
      "link" : "/wash-guide",
      "releaseDate" : "2021-10-01T00:00:00Z",
      "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
      "title" : "How to wash jeans",
      "type" : "article"
    } ],
    "sort" : {
      "options" : [ {
        "id" : "RELEVANCE",
        "label" : "Relevance"
      } ],
      "selected" : "RELEVANCE"
    },
    "totalHits" : 0
  },
  "q" : "Jean"
}
Schema

ContentSearchPageResult

The object representation of the content search page result.

Name Type Description Example
autoCorrect AutoCorrect Information about applied auto corrections to the search phrase. Omitted if no correction was made.
didYouMean DidYouMean[] A list of did-you-mean suggestions
primaryList PrimaryContentList A content list with the search result.
q string The search query used for the current result. May be corrected and differ from the requested query. "Jean"

Schemas

Inner schemas

AutoCorrect

Name Type Description Example
originalTotalHits integer The number of hits for the original search phrase. 5
q string The autocorrected suggestion. "Jeans"

ContentFilter

Content filters can be applied to most content listings and are included in the request body for the target listing. Applying a filter will restrict the set of returned content and can only be string value filters e.g. not numeric. Listing multiple attributes to filter on will restrict the content to all conditions (logical AND). When listing values within one attribute, content with any of the listed properties apply (logical OR). In addition, any custom attribute can be used as a value filter, through prefixing the attribute to be filtered with custom., for example custom.season. The following example filters on content having both a specific designer and one or both seasons listed: {"custom.designer": "Langdon","type": "article", "custom.season": ["Winter", "Spring"]} Here is a brief description of the filters available:

Name Type Description Example
content_key string[] The key(s) of the content items you wish to filter. ["a1","d2"]
custom.ATTRIBUTE string The custom attribute as the name and then the values you wish to filter on. Note that ATTRIBUTE should be replaced with a custom attribute in the data feed. "abc123"
type string[] The type(s) of the content items you wish to filter. ["article","designer"]

ContentItem

Object representation of the content item.

Name Type Description Example
custom <string, CustomAttributeResult[]> Custom attributes of the content item, represented as key-value pairs. {"tags":[{"id":"78","label":"Guide"},{"id":"223","label":"Jeans"}]}
description string Description of the content item. Undefined if omitted during import. "To wash or not to wash? And how?! Those are questions jeans shoppers are asking."
image Image Image information. Undefined if omitted during import.
key string Content identifier "wash_care"
link string Link to the page representing this content item. "/wash-guide"
releaseDate string Release date of the content item. Undefined if omitted during import. "2021-10-01T00:00:00Z"
ticket string Used in notification calls to register visitor interaction. "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7"
title string Title of the content item. "How to wash jeans"
type string Type of the content item. "article"

ContentSortOrderResult

Name Type Description Example
options SortOption[] The available sort order options
selected string The chosen sort order Supported values: RELEVANCE, NEWEST_FIRST. "RELEVANCE"

CustomAttributeResult

Name Type Description Example
id string Id of the attribute (the actual value). "summer"
label string The label of the attribute (the name attribute in the feed - currently not available for content items). "Summer"

DidYouMean

Name Type Description Example
q string A suggested correction of the original query. Never returned simultaneously as an applied autocorrection. "shoes"

Image

The object representation of an image.

Name Type Description Example
alt string Element of image specifying the alt text of an image. The alt text should describe the image. Always returned along with the image. "A woman wearing a white t-shirt"
caption string Element of image specifying the caption for the image, only returned on the product page (or content information for content). "The model is 176 cm tall and is wearing size S"
custom <string, string> Custom attributes of the image.
sources Source[]

PrimaryContentList

The object representation of the primary content list.

Name Type Description Example
items ContentItem[] A list of the result of the search.
sort ContentSortOrderResult How the content is sorted and the available sort options.
totalHits integer The total number of content item hits.

PrimaryContentListSettings

A configuration object allowing filter restrictions of the primary listing, i.e. the search results.

Name Type Description Example
contentFilter ContentFilter {"custom.designer":"Langdon","type":"article","custom.season":["Winter","Spring"]}

SortOption

Name Type Description Example
id string Identifier for the SortOption. Supported values: RELEVANCE, NEWEST_FIRST, PRICE_ASCENDING, PRICE_DESCENDING, DISCOUNT, RATING, NAME, LENGTH_INCREASING, LENGTH_DECREASING, WIDTH_INCREASING, WIDTH_DECREASING, HEIGHT_INCREASING, HEIGHT_DECREASING, DEPTH_INCREASING, DEPTH_DECREASING, VOLUME_INCREASING, VOLUME_DECREASING, WEIGHT_INCREASING, WEIGHT_DECREASING, TITLE. "RELEVANCE"
label string The presentation text for the SortOption. "Relevance"

Source

Name Type Description Example
url
Required 		string The URL of the image source. "https://cdn.example.com/img/j12_prod.jpg"
height integer The height of the image. Undefined if height was not specified. 820
width integer The width of the image. Undefined if width was not specified and hasn't yet been assessed by the image service. 420
×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE