eComm|Search accepts a set of parameters in the GET request for each search. All of the required parameters must be included in order for the request to be successful. Optional parameters are often used to state a restriction or selection of the data that can be returned.
The following parameters may be included in every request to the Ecommerce Search Tool. Required parameters must be included with each request for the request to succeed.
| Name | Description | Type | Value |
|---|---|---|---|
| client_id | The Requester's Client ID 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. |
Required | A valid Client ID |
| page | This determines what page of results will be returned upon completion of the request. |
Required | A page number between 1 and the number of pages returned from a previous request. |
| res_per_page | This determines the number of results per page. |
Optional | An integer. If res_per_page is omitted 10 results will be returned. If the results per page is higher than the number of results found, all the results will be returned. |
| keywords | These are the words the server processes to return results. If no keywords are present, there will be no results. |
Required | A word or words seperated by spaces. Most commonly submitted using a text box on a web form. Search logical operators that are supported are: |
| xml | This changes the returned results from HTML output to XML output. |
REQUIRED FOR XML | If XML is desired the xml value in the query string should be set to 1. Otherwise it can be left out of the query string. |
| ip | The IP of the person making the request. | Optional | Since the custom API will be calling the search from your server it is imperative that you pass this if you wish your reporting to be accurate on who is making the searches. If this parameter is not included your IP will be used. |
| user_agent | The user agent of the person making the request. | Optional | 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 be set to 'API Client'. |
| in_field | When this is passed, the keywords are searched for in a specific field in your database. This can produce more refined results such as searching for 'blue' in the 'color' field. |
Optional | The value must be the name of a field contained in your database. A list of your fields can be seen on the Search Refinements page. |
| sort_by_field | When the sort_by_field is included in the query string the results will be sorted by the field specified. |
Optional | The value must be the name of a field contained in your database followed by whether the sorting should be ascending order or descending order. A list of your fields can be seen on the Search Refinements page. Ascending example: name:ASC |
| searchtype | This determines when/if your search will use the ANDs to ORs search to provide a user with some results. When a user searches for blue kettle, the logic behind that search is blue AND kettle. An ANDs to ORs search changes the logic of that search to be blue OR kettle. Which could result in red kettles being found, to help ensure the user finds something within your store even if it's not exactly what he/she was looking for. |
Optional | 0 or missing - to never switch ANDs to ORs |
| synonym | This is used purely for reporting purposes. This should be included if you wish to indicate in your search reports that the user has for example, clicked on a link that denotes a synonym that you created for the keyword(s) the user entered. You can create synonyms for keywords on the Synonyms page. |
Optional | y (To indicate to the system that a synonym was used.) |
| spellcheck | Like synonym, this is used purely for reporting purposes. This should be included if you wish to indicate in your search reports that the use has for example, clicked on a like that denotes a suggested spelling of the keyword(s) that the user entered. |
Optional | y (To indicate to the system that a spell checked version of the keywords was used.) |
| refine | Like synonym and spellcheck this is used purely for reporting purposes. This should be included if you wish toindicate in your search reports that the search results have been refined. A refinement could be for example, taking all the results from searching for cigars and only returning the ones made in the US. Using this will note that refinements were used in the 'search type' column in the search report. |
HAS A DEPENDENT | y (To indicate to the system that the search was refined.) |
| <refinements> | Any other paramenters included in the query string that are not one of the above fields is considered by the system to a refinement field. These are used to reduce the number of search results returned and provide a more specific set of results. For these fields to be processed by the system, you must include the refine parameter listed above. |
HAS A DEPENDENCY | The key and value are important as this parameter is not specifically defined. The key must be a field that exists in your database. For proper refinement the value should be a value that appears in that key's column in your database. Example: Country=USA, Available=Yes |
| 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. |
Optional |
true |
Example Query Strings
1) The user wishes to see the third page of a query for 'socks', sorted by
size, that have been refined to be of type 'ladies' and color 'black'.
return-results.php?client_id=fkdosDbosj2943G&page=3&keywords=socks&sort_by_field=size:ASC&refine=y&type=ladies&color='black'
2) The user has searched for 'bleu' in the color field. You want to give
the user a link that is the spellchecked version, 'blue' and have it record
in your report that spellchecking was used.
return-results.php?client_id=fkdosDbosj2943G&page=1&keywords=blue&in_field=color&spellcheck=y