Search API Response
This document details the structure of the response from the search API. We will outline the format of the response by looking at each possible component that could return.
area
The Area of Command Center that was used when this query fired. If you didn’t specify anything, ‘Production’ will be used.
JSON Reference:
{ "area": "Production" }
availableNavigation
This section will return all the Dynamic Navigations defined in Command Center, that had available refinements for the given set of results. This portion can be used to render your left hand side navigation.
There are a few ways that this portion could return attributes that are different from what you expect:
includedNavigations: will restrict what’s returned here to only what’s defined in the queryexcludedNavigations: will remove navigations from this portion of the responsepruneRefinements: won’t return the navigations that wouldn’t change the results (same results, same count)- Controlled from Command Center: merchandisers can control which navigations are included at Rule level
- Scope of the recall: the navigations will only be returned if they contain refinements that are applicable to the recalled records
{
"availableNavigation": [
{
"name": "item.size",
"displayName": "Size",
"type": "Value",
"refinements": [
{
"type": "Value",
"count": 1,
"value": "18"
},
{
"type": "Value",
"count": 2,
"value": "16"
},
{
"type": "Value",
"count": 2,
"value": "14"
},
{
"type": "Value",
"count": 3,
"value": "12"
},
{
"type": "Value",
"count": 4,
"value": "10"
},
{
"type": "Value",
"count": 4,
"value": "8"
},
{
"type": "Value",
"count": 4,
"value": "6"
},
{
"type": "Value",
"count": 3,
"value": "4"
},
{
"type": "Value",
"count": 1,
"value": "2"
}
],
"metadata": [],
"range": false,
"or": true
},
{
"name": "item.brand",
"displayName": "Brand",
"type": "Value",
"refinements": [
{
"type": "Value",
"count": 4,
"value": "koala"
},
{
"type": "Value",
"count": 3,
"value": "bear"
},
{
"type": "Value",
"count": 3,
"value": "bulldog"
},
{
"type": "Value",
"count": 3,
"value": "eagle"
},
{
"type": "Value",
"count": 3,
"value": "gazelle"
},
{
"type": "Value",
"count": 3,
"value": "panther"
},
{
"type": "Value",
"count": 3,
"value": "penguin"
},
{
"type": "Value",
"count": 2,
"value": "giraffe"
},
{
"type": "Value",
"count": 2,
"value": "tiger"
},
{
"type": "Value",
"count": 1,
"value": "antelope"
},
{
"type": "Value",
"count": 1,
"value": "lion"
}
],
"metadata": [
{
"key": "itemsShown",
"value": "5"
}
],
"range": false,
"or": true
},
{
"name": "item.color",
"displayName": "Color",
"type": "Value",
"refinements": [
{
"type": "Value",
"count": 6,
"value": "violet"
}
],
"metadata": [],
"range": false,
"or": false
},
{
"name": "item.price",
"displayName": "price",
"type": "Value",
"refinements": [
{
"type": "Value",
"count": 1,
"value": "5.0"
},
{
"type": "Value",
"count": 1,
"value": "40.0"
},
{
"type": "Value",
"count": 1,
"value": "66.0"
},
{
"type": "Value",
"count": 1,
"value": "69.0"
},
{
"type": "Value",
"count": 1,
"value": "72.0"
},
{
"type": "Value",
"count": 1,
"value": "75.0"
}
],
"metadata": [],
"range": false,
"or": false
}
]
}biasingProfile
The biasing profile used to define the order of results within the returned products.
This can be controlled by settings at:
- Area level
- Rule level, which will override Area settings
- Query level, which will override Rule and Area settings
JSON Reference:
{ "biasingProfile": "PopularityBias" }
correctedQuery
If Autocorrection was applied, this will be returned with the corrected query. This is omitted when no autocorrect was applied.
Autocorrect
Let’s say my query of egle is autocorrected to eagle.
JSON Reference:
{ "correctedQuery": "eagle" }
didYouMean
If the query had possible alternative spellings within a close alphabetical space, alternative spellings will be returned as an array here. The didYouMean array can be used to suggest possible alternative searches.
The volume of the suggestions is controlled at Area level.
JSON Reference:
{ "didYouMean": [ "lion", "line" ] }
matchStrategy
Will return the name, if applicable, and the rules that defined the match strategy that was applied to this search. This information can be used to decide on fall-back queries (if you want to re-fire a query with a softer match strategy, for example).
The name of the match strategy is defined in Command Center.
The rules that apply to this match strategy can be defined in Command Center, or at query time.
JSON Sample:
{
"matchStrategy": {
"name": "strongMatch",
"rules": [
{
"termsGreaterThan": 1,
"mustMatch": 100,
"percentage": true
}
]
}
}
originalQuery
Returned if autocorrect, stop vword, or a spell correction via Command Center was applied.
Autocorrect
Let’s say my query of egle is autocorrected to eagle.
JSON Reference:
{ "originalQuery": "egle" }
Spelling correction via Command Center
Let’s say my query of egle is spell corrected to penguin via Command Center due to a merchandising decision.
JSON Reference:
{ "originalQuery": "egle" }
Stopwords via Command Center
Let’s say I added “record” as a stop word, and the customer searched for dress record.
JSON Reference:
{ "originalQuery": "dress record" }
pageInfo
Returns the number of the starting and last record within the response. This is 1-indexed. If your page size is larger than the number of returned records, this will return the number of the last record.
JSON Reference:
{ "pageInfo": [ { "recordStart": "1", "recordEnd": "43" } ] }
query
Holds the final text that was used in the query to the engine.
In other words, changes by the engine, like autocorrection or synonyms, are not reflected here. Changes made by a merchandiser via Command Center, like a spell correction or a stop word, are reflected here.
If synonyms are applied, only the content of this field will be used to check against the rules.
Autocorrect
If an autocorrect was applied, this will hold the original query.
Let’s say my query of egle is autocorrected to eagle.
JSON Reference:
{ "query": "egle" }
Spelling correction via Command Center
If spell correction by a merchandiser via Command Center was applied, this will hold the corrected, new query.
Let’s say my query of egle is spell corrected to penguin via Command Center due to a merchandising decision.
JSON Reference:
{ "query": "penguin" }
Stopwords via Command Center
If a stop word was added by a merchandiser, and applied against the query, this will hold the corrected, new query.
Let’s say I added record as a stopword, and the customer searched for dress record.
JSON Reference:
{ "query": "dress" }
records
This returns a nested array, with each top-level item representing a unique result in the record set.
JSON Reference:
In the below example we have 3 records from the sample data set.
Each record holds a set of mandatory fields at the top level, and content of the record under allMeta.
{
"records": [
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "light-blue",
"size": [
"4",
"6",
"8",
"10"
],
"price": "54",
"brand": "koala"
}
],
"description": "this is record number 134 - coat - this is the koala brand",
"id": "134",
"title": "my 134st record"
},
"_id": "d0f2d799a30653e6b9fe57c37ec3790d",
"_u": "http://training1trainingFlat.com/134",
"_t": "my 134st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "light-blue",
"size": [
"2",
"4",
"6",
"8"
],
"price": "16",
"brand": "koala"
}
],
"description": "this is record number 232 - coat - this is the koala brand",
"id": "232",
"title": "my 232st record"
},
"_id": "29f5a179154377cdbf585e194570fb2e",
"_u": "http://training1trainingFlat.com/232",
"_t": "my 232st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "light-blue",
"size": [
"4",
"6",
"8",
"10"
],
"price": "41",
"brand": "koala"
}
],
"description": "this is record number 330 - dress - this is the koala brand",
"id": "330",
"title": "my 330st record"
},
"_id": "df0fbd2d4d8226a8ba64c4730458fbef",
"_u": "http://training1trainingFlat.com/330",
"_t": "my 330st record"
}
]
}relatedQueries
This is an array of values populated by the Merchandiser from Command Center. In Command Center, under query rewrites there is a Related Queries section. The merchandisers can define related queries to show given a trigger word. Those queries will return as an array in this portion of the response.
For example, if we set up a list of related queries of “coat, bear, koala”:
JSON Reference:
{ "relatedQueries": [ "coat", "bear", "koala" ] }
rewrites
This will return a list of all the query rewrites that were applied to the query. The possible values within this section are:
- “
spellings” if a spell correction from Command Center was applied - “
synonyms” if synonyms were configured in Command Cente - “
stopwords” if the query included stop words that were removed from the query - “
autocorrect” if no results were found, autocorrect was not disabled, and an autocorrect was applied.
JSON Reference:
{ "rewrites": [ "stopwords", "spellings", "synonyms"" ] }
selectedNavigation
This holds all the refinements that were applied within the query, whether or not the field is defined as a Dynamic Navigation. All refinable fields can be filtered by, and this section will hold any selected filters.
JSON Reference:
{
"selectedNavigation": {
"name": "item.size",
"displayName": "Size",
"refinements": [
{
"type": "Value",
"value": "8"
}
],
"metadata": [
{
"key": "itemsShown",
"value": "5"
}
],
"_id": "6821c1b87a1dae929580bd68a916a6ca",
"range": false,
"or": true
}
}siteParams
Returns an array of key-value pairs of the metadata that was defined in the Command Center area. This is controlled by the merchandiser and can be used to define Area-wide attributes to manage the rendering or behavior of your site.
JSON Reference:
{ "siteParams": [ { "key": "backgroundColor", "value": "#ffffff" } ] }
template
This section will hold all the information about the Rule and Template that was triggered from the Command Center. If no template was defined or triggered, this will be blank.
JSON Reference:
{
"name": "Sample Template",
"ruleName": "Dress",
"zones": {
"Plain Text": {
"type": "Content",
"name": "Plain Text",
"content": "The quick brown fox jumps over the lazy dog."
},
"Special Query": {
"type": "Record",
"name": "Special Query",
"records": [
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "bright-red",
"size": [
"0",
"2",
"4",
"6"
],
"price": "68",
"brand": "lion"
}
],
"description": "this is record number 27 - coat - this is the lion brand",
"categories": [],
"id": "27",
"title": "my 27st record",
"categoryId": "5"
},
"_id": "7a19056c39a35cfb6f562a1370ef5784",
"_u": "http://training1trainingFlat.com/27",
"_t": "my 27st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "bright-red",
"size": [
"0",
"2",
"4",
"6"
],
"price": "14",
"brand": "bulldog"
}
],
"description": "this is record number 170 - T-shirt - this is the bulldog brand",
"categories": [
{
"categories": [
{
"categories": [
{
"value": "New"
}
],
"value": "New and Popular"
},
{
"categories": [
{
"value": "Casual"
}
],
"value": "Dress"
}
],
"value": "Category Root"
}
],
"id": "170",
"title": "my 170st record",
"categoryId": [
"10a",
"7b"
]
},
"_id": "7da0249b1374587c5fb422130756177e",
"_u": "http://training1trainingFlat.com/170",
"_t": "my 170st record"
}
]
},
"New Search": {
"type": "Record",
"name": "New Search",
"query": "coat",
"records": [
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "bright print",
"size": [
"0",
"2",
"4",
"6"
],
"price": "30",
"brand": "gazelle"
}
],
"description": "this is record number 8 - a-line skirt - this is the gazelle brand",
"categories": [],
"id": "8",
"title": "my 8st record",
"categoryId": "4"
},
"_id": "5913ac978b5ed8a4fe72e228f6cd1eca",
"_u": "http://training1trainingFlat.com/8",
"_t": "my 8st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "bright-red",
"size": [
"2",
"4",
"6",
"8"
],
"price": "25",
"brand": "lion"
}
],
"description": "this is record number 44 - a-line skirt - this is the lion brand",
"categories": [],
"id": "44",
"title": "my 44st record",
"categoryId": "4"
},
"_id": "78caff1054bcf8095c5ea543584811b0",
"_u": "http://training1trainingFlat.com/44",
"_t": "my 44st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "navy",
"size": [
"2",
"4",
"6",
"8"
],
"price": "97",
"brand": "giraffe"
}
],
"description": "this is record number 65 - a-line skirt - this is the giraffe brand",
"categories": [
{
"categories": [
{
"value": "Dress"
}
],
"value": "Category Root"
}
],
"id": "65",
"title": "my 65st record",
"categoryId": "2"
},
"_id": "a406d2e3528967fbc78339aea593ab64",
"_u": "http://training1trainingFlat.com/65",
"_t": "my 65st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "striped",
"size": [
"10",
"12",
"14",
"16"
],
"price": "34",
"brand": "giraffe"
}
],
"description": "this is record number 148 - a-line skirt - this is the giraffe brand",
"categories": [
{
"categories": [
{
"value": "Dress"
}
],
"value": "Category Root"
}
],
"id": "148",
"title": "my 148st record",
"categoryId": "2"
},
"_id": "44d60c779bcbdd2e7893fbfd13e582e3",
"_u": "http://training1trainingFlat.com/148",
"_t": "my 148st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "floral",
"size": [
"4",
"6",
"8",
"10"
],
"price": "64",
"brand": "panther"
}
],
"description": "this is record number 156 - a-line skirt - this is the panther brand",
"categories": [],
"id": "156",
"title": "my 156st record",
"categoryId": "3"
},
"_id": "88e29f7bfb1a33639b97d4fe9f6c3443",
"_u": "http://training1trainingFlat.com/156",
"_t": "my 156st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "blue",
"size": [
"10",
"12",
"14",
"16"
],
"price": "37",
"brand": "eagle"
}
],
"description": "this is record number 217 - a-line skirt - this is the eagle brand",
"categories": [],
"id": "217",
"title": "my 217st record",
"categoryId": "1"
},
"_id": "3cb72e2c170105d386456367f2b07483",
"_u": "http://training1trainingFlat.com/217",
"_t": "my 217st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "black-and-white",
"size": [
"0",
"2",
"4",
"6"
],
"price": "62",
"brand": "penguin"
}
],
"description": "this is record number 253 - a-line skirt - this is the penguin brand",
"categories": [
{
"categories": [
{
"categories": [
{
"value": "New"
}
],
"value": "New and Popular"
},
{
"categories": [
{
"value": "Casual"
}
],
"value": "Dress"
}
],
"value": "Category Root"
}
],
"id": "253",
"title": "my 253st record",
"categoryId": [
"10a",
"7b"
]
},
"_id": "b99607291f2ea154a35bc73f83d8ab78",
"_u": "http://training1trainingFlat.com/253",
"_t": "my 253st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "gray",
"size": [
"12",
"14",
"16",
"18"
],
"price": "58",
"brand": "panther"
}
],
"description": "this is record number 282 - a-line skirt - this is the panther brand",
"categories": [],
"id": "282",
"title": "my 282st record",
"categoryId": "5"
},
"_id": "420486fb150808173d44ad9bca8df740",
"_u": "http://training1trainingFlat.com/282",
"_t": "my 282st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "violet",
"size": [
"6",
"8",
"10",
"12"
],
"price": "32",
"brand": "giraffe"
}
],
"description": "this is record number 308 - a-line skirt - this is the giraffe brand",
"categories": [
{
"categories": [
{
"categories": [
{
"value": "New"
}
],
"value": "New and Popular"
},
{
"categories": [
{
"value": "Casual"
}
],
"value": "Dress"
}
],
"value": "Category Root"
}
],
"id": "308",
"title": "my 308st record",
"categoryId": [
"10a",
"7b"
]
},
"_id": "7428d73f5276a230e2d2d197d2a0741b",
"_u": "http://training1trainingFlat.com/308",
"_t": "my 308st record"
},
{
"collection": "trainingFlat",
"allMeta": {
"item": [
{
"color": "polka dot",
"size": [
"2",
"4",
"6",
"8"
],
"price": "42",
"brand": "penguin"
}
],
"description": "this is record number 445 - a-line skirt - this is the penguin brand",
"categories": [
{
"categories": [
{
"categories": [
{
"value": "New"
},
{
"value": "Popular"
}
],
"value": "New and Popular"
}
],
"value": "Category Root"
}
],
"id": "445",
"title": "my 445st record",
"categoryId": [
"10a",
"10b"
]
},
"_id": "932bc7c941a4f0ebe2f8fe0305169e50",
"_u": "http://training1trainingFlat.com/445",
"_t": "my 445st record"
}
]
},
"HTML Zone": {
"type": "Rich_Content",
"name": "HTML Zone",
"richContent": "<p><strong>Hello world</strong></p>\n"
}
}
}
At the top level of the template there are 3 values:
{
"name": "Filter",
"ruleName": "Dress",
"zones": { ... }
}
nameholds the name of the Template from Command CenterruleNameis the name of the Rule from Command Centerzonesis an array of the content that was populated by the merchandiser within Command Center.
Within the zones each Zone has the key of the name of the Zone as it was created in Command Center.
The value holds more information about the Zone.
In the above example, we see 4 zones, in roughly 3 types (type):
- Content
- Record
- Rich_Content
Content Zone
Content zones are created in Command Center as a “Content” and will return exactly the value that was entered within the rule. Content zones can hold HTML, comma separated values, or any other plain text.
JSON Reference:
"Plain Text": {
"type": "Content",
"name": "Plain Text",
"content": "The quick brown fox jumps over the lazy dog."
}
In the above example the zone is named “Plain Text”, and the merchandiser used the rule to populate it with “The quick brown fox jumps over the lazy dog.”
Rich Content Zone
Rich content zones are created in Command Center as a “Rich Content” and will give Merchandisers an HTML WYSIWYG editor, including a raw source code (HTML code) entry panel. While this zone doesn’t sanitize the input, it will try to ensure all the HTML tags are closed, it will try to ensure all the HTML tags are closed and possibly strip out illegal tags.
JSON Reference:
"HTML Zone": {
"type": "Rich_Content",
"name": "HTML Zone",
"richContent": "<p><strong>Hello world</strong></p>\n"
}
In the above example the zone is named “HTML Zone”, and the merchandiser used the rule to populate it with:
<p><strong>Hello world</strong></p>\n"
Record Zone (Query)
Record zones return some records, as defined by the merchandiser.
Both Query and Expert Query zones will return the type of Record.
The results will obey all settings passed in the original search query:
- the same fields as specified in the original query to the engine
- the same sort as specified in the original query
- the same biasing profile
JSON Reference:
"New Search": {
"type": "Record",
"name": "New Search",
"query": "coat",
"records": [ ... ]
}
In the above example the zone is named “New Search”. The merchandiser populated it with the search for coat.
The resulting records are the results for a search for coat, within the same Collection and Area as the original query.
Record Zone (Expert Query)
Record zones return some records, as defined by the merchandiser.
Both Query and Expert Query zones will return the type of Record.
The JSON will return the same fields as specified in the original query to the engine.
JSON Reference:
"Special Query": {
"type": "Record",
"name": "Special Query",
"records": [ ... ]
}
In the above example the zone is named “Special Query”. The merchandiser used this zone to return some specific set of records, by creating and populating the zone with a JSON structured query in Command Center. This expert JSON query is not returned in the response.
The objective for this zone is to enable your front end to show a subset of products that are generated by a more complex query than just a search term.
totalRecordCount
Returns the total number of results that came back within this query.
JSON Reference:
{ "totalRecordCount": 146 }