Search API Documentation (JSON)

Quick Start

Required Parameters

Modify Returned Results

Modify Returned Refinements

Modify Merchandising Behaviour

disable_merchandizing
ignore_redirects

Miscellaneous

Page Builder

General Information

Response Details
Formatting Details

Making a Search Call

Six parameters are required for results to be returned in XML.

client_id (aka Private Client ID): unique identifier for your account
- Example: client_id=b9d7aa2736f88c2a410dde6f66b946b5
page: denotes which group of products to return
- Example: page=3
keywords: the string that is being searched for
- Example: keywords=socks
xml: denotes if the response should be in XML (default format is HTML and is deprecated, json format is also supported using json=1, see json for details)
- Example: xml=1
ip: the IP address of the user (not your host server)
- Example: ip=18.191.234.191
user_agent: the user agent of the user (aka browser details)
- Example: user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Making a Search Call with a Filter

To make a search request that filters by a refinement (aka "filter","a facet","faceted navigation","limiter","search option") requires two additional parameters to be passed on top of the standard 6 parameters (client_id, page, keywords, xml, ip and user_agent). To denote that the results are being narrowed, add 'refine=y'. The second piece of information that should be passed to refine search results is the actual refinement and refinement option. This is denoted by listing the field name to refine by and the field option.

Format:

refine=y&{FIELD}=[:string]

Format Example:

refine=y&Brand=Billabong

Paginating through results

To cycle through the results, simply change the page number of the page desired in the Request URL.

Format:

page=[:int{>0}]

Format Example:

page=2

Sorting results

To sort the results by a field, add the following parameter to the Request URL. You can sort with ascending or descending order

Format:

sort_by_field={FIELD}:{ASC|DESC}

Format Example:

sort_by_field=Price:ASC

client_id

Required Parameter In order for the search page to process your request, you must include your client id. You can find your client ID on the Preferences page.

Format:

client_id={PRIVATE_CLIENT_ID}

Format Example:

client_id=b9d7aa2736f88c2a410dde6f66b946b5

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"refinables":{
			"Gender":{
				"values":{
					"Men":39,
					"Women":33
				}
			},
			"Price":{
				"values":{
					"Less than $100":53,
					"$100 - $200":10,
					"Greater than $200":9
				}
			},
			"Color":{
				"values":{
					"Black":20,
					"Blue":13,
					"Brown":15,
					"Green":34,
					"Grey":8,
					"Orange":4,
					"Pink":2,
					"Purple":3,
					"Red":26,
					"White":8,
					"Yellow":4
				}
			},
			
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":36,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.04",
		"results":[
			{
				"Sku":"2969",
				"Gender":"Women",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2969",
				"Price":"17.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/accessories\/121-the-second-unit-patterned-scarf\/red-the-second-unit-patterned-scarf.jpg",
				"Name":"The Second Unit Patterned Scard"
			},
			{
				"Sku":"2021",
				"Gender":"Women",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2021",
				"Price":"5.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/tops\/18-the-second-unit-jersey-tank-top\/black-jersey-the-second-unit-tank-top.jpg",
				"Name":"The Second Unit Jersey Tank Top"
			}
		],
		"index_hash":"9a9bf85b40f068dac4b009b5a70e4c2d"
	}
);

ip

Required Parameter The IP of the user making the request. This parameter is used in the reporting section of the Nextopia Control Panel. Please note that this is the IP address of the website's user, and NOT the IP address of your host server. If this parameter is not included, the system will not perform as expected.

Format:

ip={USER_IP}

Format Example:

ip=18.191.234.191

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

keywords

Required Parameter These are the word(s) the server processes to return results. If no keywords are present, there will be no results. By default, all fields that are included in your product feed will be indexed and used to determine which products to return. If you would like field(s) to be excluded from being indexed, please create a support ticket and we will be happy to make the required adjustments. Single or multiple words can be set using the keywords paramenter. Please note that the search is case insensitive.

Format:

keywords=[:string]

Format Example:

keywords=red

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

page

Required Parameter This determines what page of results will be returned upon completion of the request. By setting "page=2" in the Request URL, the second subset of products is returned. This can be confirmed by looking at the "current_page" tag. Also note that the system defaults to 10 products per page, so the "product_min" and "product_max" have values of 11 and 20 respectively. See the JSON Response Details for full details on the pagination node.

Format:

page=[:int{>0}]

Format Example:

page=2

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"refinables":{
			"Gender":{
				"values":{
					"Men":39,
					"Women":33
				}
			},
			"Price":{
				"values":{
					"Less than $100":53,
					"$100 - $200":10,
					"Greater than $200":9
				}
			},
			"Color":{
				"values":{
					"Black":20,
					"Blue":13,
					"Brown":15,
					"Green":34,
					"Grey":8,
					"Orange":4,
					"Pink":2,
					"Purple":3,
					"Red":26,
					"White":8,
					"Yellow":4
				}
			},
			
		},
		"pagination":{
			"total_products":72,
			"product_min":11,
			"product_max":20,
			"current_page":2,
			"total_pages":8,
			"prev_page":1,
			"next_page":1
		},
		"query_time":"0.04",
		"results":[
			{
				"Sku":"2969",
				"Gender":"Women",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2969",
				"Price":"17.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/accessories\/121-the-second-unit-patterned-scarf\/red-the-second-unit-patterned-scarf.jpg",
				"Name":"The Second Unit Patterned Scard"
			},
			{
				"Sku":"2021",
				"Gender":"Women",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2021",
				"Price":"5.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/tops\/18-the-second-unit-jersey-tank-top\/black-jersey-the-second-unit-tank-top.jpg",
				"Name":"The Second Unit Jersey Tank Top"
			}
		],
		"index_hash":"9a9bf85b40f068dac4b009b5a70e4c2d"
	}
);

user_agent

Required Parameter The user agent string of the agent making the request. Since the custom API will be calling the search from your server it is imperative that you pass this if you wish the reporting to include the proper user agent of the person making the search. If this parameter is not included the user agent will default to 'API Client'.

Format:

user_agent=[:string]

Format Example:

user_agent=Mozilla%2F5.0+%28Windows+NT+6.1%3B+WOW64%3B+rv%3A27.0%29+Gecko%2F20100101+Firefox%2F27.0

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

xml

Required Parameter This changes the returned results from HTML output to XML output.

Format:

xml={0|1}

Format Example:

xml=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&page=1&xml=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

abstracted_fields

Requires trim_length also be set This allows you to tell the system to cut long fields into a smaller size. trim_length, found below, is what determines the maximum length of your abstracted_fields. As opposed to trimmed_fields, which simply cuts the returned value at a specific length, abstracted_fields creates an abstract of the field whose length is determined by trim_length. This is often used instead of trimmed_fields as it will customize what's returned based by focusing the start and end of the returned value around the frequency of the keywords the user searched for in the text.

Format:

abstracted_fields={FIELD},{FIELD},{FIELD}...

Format Example:

abstracted_fields=Description,Name,Longdescription

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=strong&abstracted_fields=Description&trim_length=50&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"refinables":{
			"Gender":{
				"values":{
					"Men":39,
					"Women":33
				}
			}
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":10,
			"current_page":1,
			"total_pages":8,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.05",
		"results":[
			{
				"Sku":"2969",
				"Name":"The Second Unit Patterned Scard",
				"Description":"Jacquard-weave scarf with fringe on short sides. Size ...",
				"Price":"17.99",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2969","id":"114"
			},
			{
				"Sku":"2021",
				"Name":"The Second Unit Jersey Tank Top",
				"Description":"Fitted tank top in soft, stretch jersey with scoop neckline. ...",
				"Price":"5.99",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2021","id":"15"
			}
		]
	}
);

force_or_search

Forces the search to perform an OR search if a certain number of results are not returned. The format is two integers separated by a colon.

1st - the number of results that must be returned in any given AND search
2nd - the maximum [:int] of results you want the OR search to return (this affects refinements as well). Enter 0 if you do not wish to have a limit.

For example, force_or_search=1:10 means that the AND search must find at least one result and if it does not, switch to an OR search but only return a maximum of 10 results.

In an example query 'red mustang' has multiple words so the system defaults to using the AND operator (aka both 'red' and 'mustang' must be found for a product to be returned). This search would result in 0 products returned. By adding 'force_or_search=4:0' we tell the system that if a search has less than 4 products in the results, switch to the OR operator. The second parameter is the number of products to return. We used '0' to denote that there should not be a limit.

The or_switch node in the notices node will have a value of 1 if an or search has been used. With this you can inform your customers that this has taken place as their results might not exactly match their search.

Format:

force_or_search=[:int]:[:int]

Format Example:

force_or_search=1:10

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red%20mustang&force_or_search=1:10&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":1
		},
		"suggested_spelling":"",
		"refinables":{
			"Gender":{
				"values":{
					"Men":3,
					"Women":7
				}
			}
		},
		"pagination":{
			"total_products":10,
			"product_min":1,
			"product_max":10,
			"current_page":1,
			"total_pages":1,
			"prev_page":0,
			"next_page":0
		},
		"query_time":"0.21",
		"results":[
			{
				"Sku":"2969",
				"Name":"The Second Unit Patterned Scard",
				"Description":"Jacquard-weave scarf with fringe on short sides. Size ...",
				"Price":"17.99",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2969","id":"114"
			},
			{
				"Sku":"2021",
				"Name":"The Second Unit Jersey Tank Top",
				"Description":"Fitted tank top in soft, stretch jersey with scoop neckline. ...",
				"Price":"5.99",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2021","id":"15"
			}
		]
	}
);

initial_sort

Sets the initial sort using the API rather than the Control Panel, takes precedence over initial sort set in the Control Panel. One of your fields + a direction, the same as sort_by_field. ex: Price:ASC. The difference between initial_sort and sort_by_field is that sort_by_field will sort everything. Sort_by_field should be used when a customer clicks on a link to sort the results they are looking at. Initial sort will leave your merchandised products and other special results at the top while it sorts the rest of the regular products by the field you have specified. Initial_sort is the parameter you should use if you want your search results to come back in some other order other than relevance by default.

When you have sorted by a valid field and direction the field and direction you have sorted by will be returned in the results

Format:

initial_sort={FIELD}:{ASC|DESC}

Format Example:

initial_sort=Price:ASC

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&initial_sort=Brand:ASC&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"sorted_by":"Price:ASC",
		"refinables":{
			"Gender":{
				"values":{
					"Men":39,
					"Women":33
				}
			}
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":36,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.11",
		"results":[
			{
				"Sku":"2021",
				"Name":"The Second Unit Jersey Tank Top",
				"Price":"5.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/tops\/18-the-second-unit-jersey-tank-top\/black-jersey-the-second-unit-tank-top.jpg"
			},
			{
				"Sku":"4370",
				"Name":"The Second Unit Knit Hat",
				"Price":"5.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/accessories\/122-the-second-unit-knit-hat\/burgundy-the-second-unit-knit-hat.jpg"
			}
		]
	}
);

initial_sort_order

Requires initial_sort also be set This is for users that want the initial sort to be something like Brand:ASC but want Sony,Samsung and Apple first. When using this the sorting will follow the order given in the initial_sort_order parameter then follow the normal order that was set. In the above example it was Brand:ASC. You MUST use initial_sort either through the Control Panel or API if you want this parameter to function.

Format:

initial_sort_order=[:string],[:string],...

Format Example:

initial_sort_order=Apple,Sony

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&initial_sort=Brand:ASC&initial_sort_order=Apple,Sony&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

no_metaphones

Forces the search to not include metaphones of the keywords when searching unless the number of results falls below a set theshold. The format is two integers separated by a colon.

1st - the number of results that must be returned in the metaphone-less search. Enter 0 if you never want to include metaphones.
2nd - the maximum [:int] of results you want the metaphoned search to return (this affects refinements as well). Enter 0 if you do not wish to have a limit.

In our example, we add 'no_metaphones=4:10' which tells the system that if there are 4 or more products in the results, do not use metaphones (ref: http://en.wikipedia.org/wiki/Metaphone). If less than 4 products to return, use metaphones to return 10 products. We can remove this limit restriction by changing the 4 to a 0.

Format:

no_metaphones=[:int]:[:int]

Format Example:

no_metaphones=4:10

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&no_metaphones=4:2&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

no_stemming

Forces the search to not include stemming of the keywords. 1 to activate it, anything else will be ignored. In our example, if we did not add 'no_stemming=1', the search would have stemmed 'fishing' to its root 'fish'.

Format:

no_stemming={0|1}

Format Example:

no_stemming=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=fishing&no_stemming=1&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

refinements

Requires refine also be set Any parameters that match your fields are considered to be refinements(also known as filters or facets). By passing these fields along with your keywords you can reduce the number of search results that are returned and provide a more specific set of results. For these fields to be processed by the system you must also include refine=y within the querystring.

If you wish to pass multiple values to a refinement you can separate them using a caret (ex: Brand=Nike^Reebok). This tells the search to match the products where Brand is Nike OR Reebok.

The functionality for multiple values using the caret can be altered with the and_refines parameter. Using this parameter you can change the OR in the above example to AND. For example if you had televisions with features you might want to pass 'Features=LED^3D&and_refines=Features'. This tells the system that instead of matching products that have LED OR 3D as a feature that it must have LED AND 3D in its features field. You can check our feed specification to learn how to provide multiple values to a single field within a product.

Please see the Modify Returned Refines section for more details on refinements.

When you have refined by a valid field the fields you have refined by will be returned in the results in user_search_depth

Format:

refine=y&{FIELD1}=[:string]&{FIELD2}=[:string]

Format Example:

refine=y&Brand=Flipo&Gender=Men

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&Brand=Flipo&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"suggested_spelling":"jared",
		"refinables":{
			"Category1":{
				"values":{
					"Accessories":3,
					"Bottoms":2,
					"Jackets":2,
					"Shoes":1,
					"Tops":1
				}
			}
		},
		"user_search_depth":[
			{
				"key":"Brand",
				"value":"Kenflat"
			}
		],
		"pagination":{
			"total_products":9,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":5,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.05",
		"results":[
			{
				"Name":"KenFlat Leather Chukka Boot",
				"Sku":"8093"
			},
			{
				"Name":"KenFlat Croc Wool Scarf",
				"Sku":"2733"
			}
		]
	}
);

refine

Whenever a refinement is used to narrow down a search, 'refine=y' should be added to the Request URL. By supplying this parameter, the system will know to look for refinements in the Request URL. In our example above, 'refine=y' is set since we want only products with 'Blue' in the Color field (e.g. 'Color=Blue').

Format:

refine=y

Format Example:

refine=y

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&refine=y&Color=Blue&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

requested_fields

This allows you to tell the system what fields should be returned when a search is made. Normally when a search is made, the returned results contains the values for the returned page of items that are not blank. As most searches only show a few key fields such as name, description, image, price it is not necessary to return other fields such as length, height or size if they are not going to be shown. Doing this increases the speed of the search as the returned data is smaller.

Format:

requested_fields={FIELD1},{FIELD2},...

Format Example:

requested_fields=Name,Price,Sku,Image

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&requested_fields=Sku,Name&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

res_per_page

This determines the number of results to return per page. The maximum number of products we allow to be returned per page is 100.

Format:

res_per_page=[:int{1..100}]

Format Example:

res_per_page=4

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&res_per_page=4&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

searchtype

This determines whether or not your results will fall back to an OR search when no results are found using an AND search. When a user searches for 'red mustang', the logic behind that search is to return products that have both red and mustang in their data. If the operation is changed to OR the system will search for products that contain red OR mustang. The OR operator is used to ensure that the user finds something within your store even it is not exactly what he/she was looking for. Set this parameter to 0 to never switch ANDs to ORs. Setting it to 1 will switch ANDs to ORs if no products are found.

This functionality is somewhat deprecated as force_or_search will give you greater control on when to use OR searching.

Format:

searchtype={0|1}

Format Example:

searchtype=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red%20mustang&searchtype=1&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

sort_by_field

When the sort_by_field is included in the querystring the results will be sorted by the field specified. Products you have merchandised will no longer be at the top, they will be sorted in with the rest of the results. See initial_sort if you wish to sort but keep your merchandised products at the top of the results.

When you have sorted by a valid field and direction the field and direction you have sorted by will be returned in the results

Format:

sort_by_field={FIELD}:{ASC|DESC}

Format Example:

sort_by_field=Price:ASC

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&sort_by_field=Price:ASC&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"sorted_by":"Price:ASC",
		"refinables":{
			"Gender":{
				"values":{
					"Men":39,
					"Women":33
				}
			}
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":36,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.11",
		"results":[
			{
				"Sku":"2021",
				"Name":"The Second Unit Jersey Tank Top",
				"Price":"5.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/tops\/18-the-second-unit-jersey-tank-top\/black-jersey-the-second-unit-tank-top.jpg"
			},
			{
				"Sku":"4370",
				"Name":"The Second Unit Knit Hat",
				"Price":"5.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/accessories\/122-the-second-unit-knit-hat\/burgundy-the-second-unit-knit-hat.jpg"
			}
		]
	}
);

trim_length

Requires trimmed_fields or abstracted_fields also be set Helper function. This controls the length of the returned value for any fields present in abstracted_fields and trimmed_fields. If this value is not set the returned values for abstracted_fields and trimmed_fields will not be correct.

Format:

trim_length=[:int{>0}]

Format Example:

trim_length=50

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&trimmed_fields=Description&trim_length=25&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

trimmed_fields

Requires trim_length also be set This allows you to tell the system to cut long fields into a smaller size. The parameter, trim_length, is what determines the maximum length of your trimmed_fields. When showing a description of a product it is often not useful to show the whole thing, especially if the description contains minute details that would be better left for the detail page for the product. This allows you to cut the size of the field on the server-side rather than the client-side which increases the speed of the search as the resulting JSON is smaller.

Format:

trimmed_fields={FIELD1},{FIELD2},...

Format Example:

trimmed_fields=Description,Longdescription

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&trimmed_fields=Description&trim_length=25&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

and_refines

Normally, when passing refinements with multiple values (ex: Brand=Nike^Reebok) you are asking the system to return any products that have a Brand of Nike OR Reebok. Sometimes however you have multiple values in a field such as Features (ex: in features for a TV it could be an LED screen and a 3D TV) and you want the system to return products that match ALL the refinement values sent over(ex: Features=3D^LED). To do this use the and_refines parameter(ex: and_refines=Features). By sending this you are telling the system that when matching products on the denoted refinements the product must have all the values in the field instead of having any one of the values denoted. You can check our feed specification to learn how to provide multiple values to a single field(such as features) within a product.

Format:

and_refines={FIELD1},{FIELD2},...

Format Example:

and_refines=Features

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&and_refines=Features&Features=3D^LED&page=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

compact_refines

If your refinement data is large and is slowing down your search you can use compact_refines to trim down the data. Instead of there being a value node for each value in a refinement they will be returned in a single values node. Each value set will be separated by a tilde (~). The value and the number of products that have that refinement will be separated by a caret(^). Please see the example below.

Format:

compact_refines={0|1}

Format Example:

compact_refines=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&compact_refines=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices": {
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"refinables":{
			"Brand":{
				"values":"BRIDGE THE GAP^3~C.James^16~Jake&Juliet^3~KatAnn^9~KenFlat^9~Lack Luster^3~SAFARI^2~T2^2~The Second Unit^21~UrbanRevolt^4"
			},
			"Color":{
				"values":"Black^20~Blue^13~Brown^15~Green^34~Grey^8~Orange^4~Pink^2~Purple^3~Red^26~White^8~Yellow^4"
			},
			"Category1":{
				"values":"Accessories^18~Bottoms^14~Dresses^2~Jackets^10~Shoes^8~Tops^20"
			}
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":1,
			"current_page":1,
			"total_pages":72,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.05",
		"results":[
			{
				"Sku":"2969",
				"Gender":"Women",
				"Price":"17.99",
				"Brand":"The Second Unit",
				"Name:"The Second Unit Patterned Scard"
			}
		]
	}
);

custom_ranges

Create custom ranges on any numeric field. You can also set this using the Search Refinements page in the Nextopia Admin Panel. The format is as follows:

field:min,max,label|min,max,label^field:min,max,label|...

In our example, 'Price:0,10,Under $10|10.01,100000,Over $10' was added which modified how the Price field was returned. The result will put all of the products into the defined ranges (0-10,10.01-100000).

Please note that this parameter can only be used if all values in this field are numeric (e.g. 12" or 12x20 both would NOT work).

Format:

custom_ranges={FIELD1}:[:int],[:int],[:string]|[:int],[:int],[:string]|...^{FIELD2}:[:int],[:int],[:string]|[:int],[:int],[:string]|...

Format Example:

custom_ranges=Price:0,10,Under $10|10,100000,Over $10

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&custom_ranges=Price:0,10,Under $10|10.01,100000,Over $10&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"refinables":{
			"Price":{
				"values":{
					"Under $10":6,
					"Over $10":66
				}
			}
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":36,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.05",
		"results":[
			{
				"Name":"The Second Unit Patterned Scard",
				"Sku":"2969"
			},
			{
				"Name":"The Second Unit Jersey Tank Top",
				"Sku":"2021"
			}
		]
	}
);

paginate_refines

If your refinement data is enormous and even compact refines is not enough you can also paginate your refinements. Paginating a refine will cause ALL the refines to come back in a compacted form.

To paginate a refinement there are four values you need to provide. If you wish to create different pagination for multiple refines you can include multiple sets of information separated by two pipes together in this parameter.

1st - The name of the refinement you wish to paginate. If you wish to paginate all refinements the same way, you can put * as the name and it will affect all the refinements returned. If you explicitly define information for one or more refines and pass a set of data for * as well, * will apply itself to every refinement you have not defined.
2nd - The number of values per page you wish to return. If you pass 0 for this value all refine values will be returned.
3rd - The current page you want to retrieve.
4th - The sorting method you wish to use for the refinement values. Currently only 'N' is supported if you wish to sort numerically, descending, by the [:int] of products found within a refinement value. Pass anything else here, such as 0, to use the default alphabetic refinement sorting method.

In addition to supporting normal pagination, an "even more" approach can be taken, where "even more" means to return all the refinement values rather than paginating them. If you only want to show the first 30 refinement values for all the refinements you would use *:30:1:0. A user then asking for page two of Artists would then require *:30:1:0||Artists:30:2:0. If you wish to return all the refines for a specific refinement when someone hits "more" you could instead pass this: *:30:1:0||Artists:0:1:0. By asking for page 1 with 0 per page, you are instructing return-results to return all the values.

Note that the has_next_page node contains a 0 or a 1 that lets you know whether or not there are more refinement results that have not been shown. If you are creating an AJAX search that responds to a "more" button click you will likely want to use requested_refinements, requested_fields, and res_per_page=1 to reduce the amount of data that comes back since you are only looking to update that single refinement.

Format:

paginate_refines={FIELD1}:[:int]:[:int]:{0|N}||{FIELD2}:[:int]:[:int]:{0|N}...

Format Example:

paginate_refines=Brand:6:1:0||Category1:6:1:0

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&paginate_refines=Brand:6:1:0&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"refinables":{
			"Brand":{
				"values":"BRIDGE THE GAP^3~C.James^16~Jake&Juliet^3~KatAnn^9~KenFlat^9~Lack Luster^3",
				"has_next_page":"1"
			},
			"Price":{
				"values":"Less than $100^53~$100 - $200^10~Greater than $200^9"
			}
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":36,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.06",
		"results":[
			{
				"Name":"The Second Unit Patterned Scard",
				"Sku":"2969"
			},
			{
				"Name":"The Second Unit Jersey Tank Top",
				"Sku":"2021"
			}
		]
	}
);

refines_mode

Normally once a customer has refined by a field such as Brand you do not want the brand refinement to show up any more. In the case that you are creating refinements with checkboxes so a customer can selected multiple values you will likely want to set the refines mode for that refinement to keep. That way, when you have refined by that field it will still come back with all the values available to it based on other refinement selections that have occurred. See refinements for details on passing multiple values (ex: using checkboxes) to a single refinement.

Format:

refines_mode=keep:{FIELD1},{FIELD2},... alternatively you can simply pass refines_mode=keep to make all refines follow this mode

Format Example:

refines_mode=keep:Brand,Category

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&refines_mode=keep:Brand&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

requested_refines

This allows you to tell the system what refinements to return as an alternative to using the Control Panel. Using this also overrides any settings you set using the Control Panel. A main use of this is to speed up your search if you have tiered refinements such as category and sub-category. You can code the client to only return the sub-category if the user has refined by category and thusly only return sub-categories when needed and only sub-categories that are relevant to the category the user has refined with.

Format:

requested_refines={FIELD1},{FIELD2},...

Format Example:

requested_refines=Brand,Category

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&requested_refines=Brand&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

return_single_refines

Allows you to return a refinement that has a single value.

Use 1:0 if you always want to return single refines. Use 1:1 if you only want it to return the single refinement if it will reduce the number of results found.

Normally refinements will only return if multiple values are available. This allows you to have the refinement return even if there is only one value available. Most often our customers use this in a field such as 'Deals'. Where the value for most products will be blank but for some it will be 'ON SALE!' or 'FREE SHIPPING!'. You might not want a 'Free Shipping' field with 'Yes' or 'No' coming back. By using the 'Deals' field instead you can have a single value that comes back such as 'Free Shipping'.

Format:

return_single_refines=1:{0|1}

Format Example:

return_single_refines=1:1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&return_single_refines=1:0&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

disable_merchandizing

All merchandising such as products promotion and promo banners will be ignored. Please note that the merchandizing tag has been completely removed from the result.

Format:

disable_merchandizing={0|1}

Format Example:

disable_merchandizing=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&disable_merchandizing=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

ignore_redirects

Ignores redirection rules that may be set in the merchandising section of the control panel and performs the search instead.

Format:

ignore_redirects={0|1}

Format Example:

ignore_redirects=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&ignore_redirects=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

cache_call

This is used to simply have the system log a search query string instead of performing the search. The most practical use for this is if you cache search results pages for quicker loading on common searches. You simply need to append this to the end of the query string that is sent to the Nextopia server.

Format:

cache_call={0|1}

Format Example:

cache_call=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&cache_call=1json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

min_max_values

Returns the min and max values for the fields listed in the value. They will be returned in a node called value_limits. Note that this requires returning the field values for the entire result set so if many limits are requested across a large number of results it could potentially slow the search down. If the numeric field contains blank values they will be changed to 0

Min-Max values only work on numeric fields that contain a single value.

Format:

min_max_values={FIELD1},{FIELD2},....

Format Example:

min_max_values=Price

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&min_max_values=Price&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"value_limits":{
			"Price":{
				"min":"5.99",
				"max":"577.99"
			}
		},
		"refinables":{
			"Price":{
				"values":{
					"Less than $100":53,
					"$100 - $200":10,
					"Greater than $200":9
				}
			}
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":36,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.06",
		"results":[
			{
				"Name":"The Second Unit Patterned Scard",
				"Sku":"2969"
			},
			{
				"Name":"The Second Unit Jersey Tank Top",
				"Sku":"2021"
			}
		]
	}
);

related_searches

This, when turned on, provides related searches info to the user. Related searches data is refreshed every sunday. Related searches are generated by:
1. Getting all the searched keywords and the count of the [:int] of times it was searched for.
2. Taking the top 1000 keywords and checking if each exists in longer keyword searches. If so, that becomes a related search.
3. Taking the related searches for each top keyword and storing the top 5% based on how many times they were searched for.

'ipod' could yield 'ipod nano' but 'ipod nano' would never yield 'ipod' since it is shorter.

When there are multiple related searches returned they are separated by ||.

Format:

related_searches={0|1}

Format Example:

related_searches=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&related_searches=1&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"related_searches":"red shirt||red shoes||shoes||shirts||shirt",
		"suggested_spelling":"jared",
		"value_limits":{
			"Price":{
				"min":"5.99",
				"max":"577.99"
			}
		},
		"refinables":{
			"Price":{
				"values":{
					"Less than $100":53,
					"$100 - $200":10,
					"Greater than $200":9
				}
			}
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":36,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.06",
		"results":[
			{
				"Name":"The Second Unit Patterned Scard",
				"Sku":"2969"
			},
			{
				"Name":"The Second Unit Jersey Tank Top",
				"Sku":"2021"
			}
		]
	}
);

json

Returns the output in JSON format. Passing callback={function name} will encase the JSON output in {function name} as per the JSONP standard. The structure is mostly the sme as the XML entities. Example output can be seen below.

Format:

json={0|1}

Format Example:

json=1

Example Request URL:

https://ecommerce-search.nextopiasoftware.com/return-results.php?keywords=red&json=1&client_id=b9d7aa2736f88c2a410dde6f66b946b5&ip=18.191.234.191&user_agent=Mozilla%2F5.0+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%3B+compatible%3B+ClaudeBot%2F1.0%3B+%2Bclaudebot%40anthropic.com%29

Show Response

callback(
	{
		"merchandizing":"<p><img src=\"\/\/nxtuploads.s3.amazonaws.com\/bda134475af25c1f2782ba03cfc4793e\/blackfriday-banner.jpg\" alt=\"\"><br><\/p>",
		"notices":{
			"related_added":0,
			"sku_match":0,
			"or_switch":0
		},
		"suggested_spelling":"jared",
		"refinables":{
			"Gender":{
				"values":{
					"Men":39,
					"Women":33
				}
			},
			"Price":{
				"values":{
					"Less than $100":53,
					"$100 - $200":10,
					"Greater than $200":9
				}
			},
			"Color":{
				"values":{
					"Black":20,
					"Blue":13,
					"Brown":15,
					"Green":34,
					"Grey":8,
					"Orange":4,
					"Pink":2,
					"Purple":3,
					"Red":26,
					"White":8,
					"Yellow":4
				}
			},
			
		},
		"pagination":{
			"total_products":72,
			"product_min":1,
			"product_max":2,
			"current_page":1,
			"total_pages":36,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.04",
		"results":[
			{
				"Sku":"2969",
				"Gender":"Women",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2969",
				"Price":"17.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/accessories\/121-the-second-unit-patterned-scarf\/red-the-second-unit-patterned-scarf.jpg",
				"Name":"The Second Unit Patterned Scard"
			},
			{
				"Sku":"2021",
				"Gender":"Women",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2021",
				"Price":"5.99",
				"Image":"http:\/\/demostore.nextopia.com\/img\/women\/tops\/18-the-second-unit-jersey-tank-top\/black-jersey-the-second-unit-tank-top.jpg",
				"Name":"The Second Unit Jersey Tank Top"
			}
		],
		"index_hash":"9a9bf85b40f068dac4b009b5a70e4c2d"
	}
);

Making a Page Builder Call

Making a page builder request is very similar to making a search call. The only difference in parameters is that instead of sending a request using the keyword parameter you instead use the nxt_landing_page parameter.

The response types that come from page builder requests are detailed below.

Format:

nxt_landing_page={PAGE_BUILDER_RULE_NAME}

Format Example:

nxt_landing_page=summersale

Valid Page Builder Response

When you make a valid call to a non-expired rule that you have created the XML will be returned much like the XML in a search response.

Note the extra node named landing_page_info. This node contains information about the rule that was matched.

matched_rule: This is the id of the rule that was matched.
is_currently_expired: Whether or not the rule you matched has expired or not. See Expired Page Builder Response
banner_html: This contains the banner html for the banner you may have created in your page builder rule.

Show Response

callback(
	{
		"landing_page_info":{
			"matched_rule":"6",
			"is_currently_expired":"0",
			"banner_html":"<p><b><i>CHECK OUT OUR SUMMER SALE<\/i><\/b><\/p>\r\n"
		},
		"notices":{
			"related_added":0,
			"sku_match":0
		},
		"refinables":{
			"Gender":{
				"values":{
					"Men":4,
					"Women":6
				}
			}
		},
		"pagination":{
			"total_products":10,
			"product_min":1,
			"product_max":3,
			"current_page":1,
			"total_pages":4,
			"prev_page":0,
			"next_page":1
		},
		"query_time":"0.04",
		"results":[
			{
				"Sku":"2574",
				"Name":"Lack Luster Adriana Point Toe Heel",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/2574"
			},
			{
				"Sku":"8361",
				"Name":"C.James Everly Satin Heel",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/8361"
			},
			{
				"Sku":"8158",
				"Name":"Nina West Super Stardom Heel",
				"Url":"http:\/\/demostore.nextopia.com\/detail\/8158"
				"nxt_spotlight":"\/\/cdn.nextopia.net\/img\/spotlight-images\/spotlight-t-new.png"
			}
		]
	}
);

Expired Page Builder Response

When you make a call to an expired rule that you have created the XML will be returned similar to that of an XML search response that has no products found. If you have created a custom expiry message you will find your message within the custom_expiry_html node found within the landing_page_info node. If you have not created a custom expiry message this node will not be present. Note that the is_currently_expired value returned is 1, meaning the rule has expired.

Show Response

callback(
	{
		"landing_page_info":{
			"matched_rule":"5",
			"is_currently_expired":"1",
			"custom_expiry_html":"<p>Too LATE<\/p>"
		},
		"notices":{
			"related_added":0,
			"sku_match":0
		},
		"pagination":{
			"total_products":0
		},
		"query_time":"0.04",
		"results":null
	}
);

Invalid Page Builder Response

When you make a call to a rule that does not exist the XML will be returned similar to that of an XML search response that has no products found. The only node contained within landing_page_info is matched_rule and its value will be 0, denoting that no rule has been matched.

Show Response

callback(
	{
		"landing_page_info":{
			"matched_rule":0
		},
		"notices":{
			"related_added":0,
			"sku_match":0
		},
		"pagination":{
			"total_products":0
		},
		"query_time":"0.05",
		"results":null
	}
);

Response Details

The Ecommerce Search Tool can return JSON results. Listed below are the JSON entities that can be returned and their format.

Type single denotes a single value contained within the entity tags. Type repeating denotes an entity that contains numerous entries of the italicized portion of the structure.

ENTITY	STRUCTURE	TYPE	DESCRIPTION
query_time	"query_time":"[:string]"	SINGLE	The time it took to complete the search.
suggested_spelling	"suggested_spelling":"[:string]"	SINGLE	Suggested spelling of the keywords or blank if there are no suggestions.
pagination	"pagination":{ "total_products":[:int], "product_min":[:int], "product_max";[:int], "current_page":[:int], "total_pages":[:int], "prev_page":[:int{0\|1}], "next_page":[:int{0\|1}] }	SINGLE	Product min - the lowest product in the results Product max - the highest product in the results (ie: Products shown <min> - <max> of <total>) Prev Page/Next Page - contains either a 1 or a 0. 1 dictates that there is a page to go back to or on to. 0 dictates that there is no next or previous page. These were added for convenience sake as you could compare the current_page to total_pages.
user_search_depth	"user_search_depth":[ { "key":"{FIELD}", "value":"[:string]", } ]	REPEATING	A list of refinements that have been done on the search to make the results more specific. The key is the field in your database that it applies to and the value is the value that has been applied to it.
sorted_by	"sorted_by":"{FIELD}:{ASC\|DESC}"	SINGLE	The field that the results are currently sorted by.
notices	"notices":{ "related_added":[:int{0\|1}], "sku_match":[:int{0\|1}], "or_switch":[:int{0\|1}], "added_metaphones":[:string] }	SINGLE	A list of notices that may be relevant to your search site. At present only one notice exists but more may be added in the future. related_added - either 0 or 1. If this flat is set to 1 it means that related products were added to the results to fill out the page. sku_match - either 0 or 1. If this flag is set to 1 it means that the result(s) returned are the product of doing a SKU (or partial SKU) match. or_switch - either 0 or 1. If this flag is set to 1 it means your search has switched the ANDs in the keyword statement to ORs. This will always be 0 unless you have enabled the switching of ANDs to ORs using the API. added_metaphones - when you ask for no metaphones using no_metaphones this notice will be passed containing a string to denote that metaphones were added back in because the number of results is less than you specified with the no_metaphones parameter. If no metaphones were added this node will not exist.
merchandizing&	"merchandizing":"[:string]"	SINGLE	If this node is present it will contain your merchandising banner HTML code or your redirect link. A redirect link will be prepended with link:.
refinables	"refinables":{ "{FIELD}":{ "values":{ "[:string]":[:int], "[:string]":[:int], ... } }, ... }	REPEATING	A list of the refinables that are available based on the results returned. Each repeated refinable is a different field you've chosen to allow refinables for. The name is the name of the field in your database such as country. The value elements repeat inside values for each refinement value returned for that refinable. The key is the value that denotes the common property among a number of results, such as country being USA and num denotes the number of results that share that property.
refinables Compacted	"refinables":{ "{FIELD}:{ "values":{ "[:string]^[:int]~... } }, ... }	REPEATING	Compacted refines have the same general syntax as regular refines but to cut down on JSON for larger sets of refines each individual refine value and count are no longer contained in elements. They are instead a string delimited by specific characters. A caret(^) is used to separate the refinement value such as "Shoes" from the number of products found within it. A tilda(~) is used to separate the sets of refinement values and their counts.
refinables Paginated	"refinables":{ "{FIELD}:{ "values":{ "[:string]^[:int]~... }, "has_next_page":[:int{0\|1}] }, ... }	REPEATING	Paginated refine values follow the same format as the compacted refines. has_next_page will contain a 0 or 1 denoting whether or not another page of refine values exists based around the current page & number per page you have requested.
results	"results":[ { "{FIELD1}":"[:string]", "{FIELD2}":"[:string]", ... "nxt_spotlight":"[:string]" }, ... }	REPEATING	A list of the results that are returned based on the requested search. Each result is contained in its own object within the results element. If the result has been included in a spotlighting rule the nxt_spotlight element will be returned with a link to the image you wanted to spotlight the product with. We recommend using an image that can be attached to the top left of your product image or beneath it within your search page layout.
custom_nrf_content	"custom_nrf_content":"[:string]"	SINGLE	If you have set up custom no results found text in the admin this tag will be returned with your text when a search yields no results.
landing_page_info	"landing_page_info":{ "matched_rule":[:int], "is_currently_expired":[int{0\|1], "custom_expiry_html":"[:string]", "banner_html":"[:string]" }	SINGLE	Information pertaining to a page builder rule call made to the system. matched_rule - either 0 or the ID of the rule that was matched. Whether or not a landing page rule was found to match the rule name passed to the system. If this is returned as 0 none of the other nodes in the landing_page_info element will not exist as no rule was matched. is_currently_expired - either 0 or 1. Whether or not the matching rule was expired or not. custom_expiry_html - Contains user defined html to be displayed if a customer uses an expired landing page. This node only exists if the matching rule is expired and there is custom html to be displayed. banner_html - Contains user defined html to be displayed if banner code has been entered. This node only exists if the matching rule is not expired and banner html code exists. Please see the Page Builder section for more information.
related_searches	"related_searches":"[:string]"	SINGLE	Contains a \|\| separated string of searches related to the current keywords.

Formatting Details

Note: Do not include the curly braces when substituting information

Entity	Description
{PRIVATE_CLIENT_ID}	Unique identifier for each Nextopia Account. Can be located on the Account Page in the Control Panel.
{FIELD}	Any column in your feed that can be used as a refinement (aka all fields excluduing Sku, Price, Name, Description, Url or Image). Available fields can be found on the Search Refinement page of the Control Panel.
{FIELD1},{FIELD2},...	A list of refinements separated by commas. One or more refinements may be included.
{FIELD1_OPTION}	Any value that can be found in {FIELD1}. E.g. If {FIELD1} = Color, it is possible that {FIELD1_OPTION} = Black
{ASC\|DESC}	When a bar is used, it represents the OR operator. Select one of the options. Note: quotation marks should not be included.
{BROWSER_DETAILS}	AKA User Agent
[:int]	An integer. E.g. 3, 0, 2000
[:string]	A URL encoded string without quotation marks.
[:int{0 ... 10}]	An integer between 0 and 10 inclusively.
[:nothing]	Parameter is optional. There is a default that will be used if omittted. Note: if the default will be used, the previous colon should be omitted.