Search Engine
In order to get started with any Prefixbox product you will need to first implement Analytics – all of our products learn and continuously improve based on this data, so analytics is a key part of a great search.
To get started with our analytics:
In order to activate the detailed search analytics, there are a few additional JavaScript calls that you need to implement on your site. Details are described here: PREFIXBOX PAGE EVENTS. Based on the detailed search analytics, Prefixbox can compute the correct order of the suggestions.
Product feed URL
To configure the search engine we need a product feed that contains all products that can be purchased on your site.
Please share this on an HTTP or HTTPS URL (public or password protected). We are going to refresh this list by downloading it from this URL multiple times per day.
Product feed format documentation: JSON FEED FORMAT.
API Call
You can call your configured search engine via HTTP GET:
https://serving5.prefixbox.com/?btr=BoxTracker &pfbuid=PrefixboxUserId &pfbsesid=PrefixboxSessionId &ip=EndUserIPAddress &pattern=Term &format=json&page=PageNum &top=TopNum&filter=Filters &orderby=OrderField OrderDir
Note: please make the API domain name (serving5.prefixbox.com) configurable in case this changes in the future. serving5.prefixbox.com has 2 data centers hosting configured for increased availability.
The request must contain at least the following two query string parameters:
| BTR=BOXTRACKER | The tracker of your search engine, you can get it from Prefixbox Portal, or from the Customer Success Manager. |
| PATTERN=TERM | The pattern / search term the user is searching for. |
The following query string parameters are optional:
| PFBUID=PREFIXBOXUSERID | The unique user identifier which can be found in the Prefixbox cookie. The cookie key: “_pfbuid”. |
| PFBSESID=PREFIXBOXSESSIONID | The unique session identifier which can be found in the Prefixbox cookie. The cookie key: ”_pfbsesid”. |
| IP=ENDUSERIPADDRESS | The IP address of the end user (webshop user). |
| TOPNUM | The number of the search results to be displayed on one page (SERP), default is specified by the search settings on the Prefixbox Portal. |
| PAGENUM | The number of the result page to be shown. |
| FILTERS | The filter conditions by which the search results will be filtered (in addition to the search term). |
| ORDERFIELD | The name of the field by which the search results will be ordered. The default order of the search results is by relevance specified by the automatically calculated Score field. |
| ORDERDIR | The direction of the ordering. Applicable values are asc and desc. The default order direction is ascending. |
Filters
You can specify filters in the Search API request for all your searchable and facetable product attributes. The format of the filters follow the OData filter URI conventions. (OData Uri Conventions Paragraph 4.5 Filter System Query Option)
For example:
- “(Price gt 2000) and (Price lt 50000)”.
- “(Category eq ‘Laptop’) and (Brand eq ‘ASUS’)”
Logical operators for filtering:
- lt – lower than
- gt – greater than
- le – lower or equal
- ge – greater or equal
- eq – equals (only for textual type fields)
You can combine any number of filters by using the and / or filter operators. You can negate any filter condition by using the not operator.
When combining filters please always make sure of the proper precedence by using brackets.
Search Response Format
After calling our search API, the response returns in JSON format.
The response contains the following main parts:
Documents
The search results themselves and additional info.
| DOCUMENTS | Object. Wrapper object for the collection of the search results. |
| COUNT (DOCUMENTS.COUNT) | Number. The number of results returned by this search. |
| RESULTS (DOCUMENTS.RESULTS) | Array of Result. The products / results returned by this search. |
| RESULT (DOCUMENTS.RESULTS[I]) | Object. Wrapper object for a single search result. |
| SCORE (DOCUMENTS.RESULTS[I].SCORE) | Number. The relevance (matching score) of the search result represented by a number. |
| DOCUMENT (DOCUMENTS.RESULTS[I].DOCUMENT) | Object. A single search result (a product). |
Filters
There are two types of facet filters.
| FILTERS | Object. Wrapper object for the filters. |
| RANGEFILTERS | This will contain facets for numerical values, like Price. RangeFilters contain a name field, this is the name of your field, and the minimum and maximum value of the filter. |
| RANGEFILTERS (FILTERS.RANGEFILTERS) | Array of RangeFilter objects. The range filters applicable for the returned search results. |
| RANGEFILTER (FILTERS.RANGEFILTERS[I]) | Object. A single range filter. |
| NAME (FILTERS.RANGEFILTERS[I].NAME) | String. The name of the range filter. Matches the name of the column on which the filter can be applied. |
| DISPLAYNAME (FILTERS.RANGEFILTERS[I].DISPLAYNAME) | String. A friendly name for the filter that can be displayed on the UI. |
| MIN (FILTERS.RANGEFILTERS[I].MIN) | Number. The lower value of the filter. |
| MAX (FILTERS.RANGEFILTERS[I].MAX) | Number. The upper value of the filter. |
| VALUEFILTERS | This will contain facets for textual facets, like Brand or Category. ValueFilters contain a name field, this is the name of your field, the number of facets returned, and the values of the facets. Every facet value contains the name and the number of products in that facet. |
| VALUEFILTERS (FILTERS.VALUEFILTERS) | Array of ValueFilters objects. The value filters applicable for the returned search results. |
| VALUEFILTER (FILTERS.VALUEFILTERS[I]) | Object. A single value filter. |
| NAME (FILTERS.VALUEFILTERS[I].NAME) | String. The name of the value filter. Matches the name of the column on which the filter can be applied. |
| DISPLAYNAME (FILTERS.VALUEFILTERS[I].DISPLAYNAME) | String. A friendly name for the filter that can be displayed on the UI. |
| VALUEFILTERVALUE (FILTERS.VALUEFILTERS[I].VALUES[J]) | Object. Contains a value by which the results can be filtered and the number of the current search results with the specified value. |
| NAME (FILTERS.VALUEFILTERS[I].NAME) | String. The name of the value filter. Matches the name of the column on which the filter can be applied. |
| COUNT (FILTERS.VALUEFILTERS[I].VALUES[J].COUNT) | Number. The number of the current search results with the specified value. |
| VALUE (FILTERS.VALUEFILTERS[I].VALUES[J].VALUE) | String. A value by which the results can be filtered. |
Other info
| COUNT | Number. The total number of results that match this search. (It is identical to the Documents.Count). |
| PAGESIZE | Number. The current page size in the request. Matches the top query string parameter specified in the search request, or the page size setting of the search box if the parameters is missing. |
Recommendation for using filters:
When the user searches for the first time (no filters specified) the API response contains the filters list. Use this for rendering the filters on the UX. When the user selects a Filter, the API request/response changes the filters. You have two options:
- [Recommended] Keep the original filters of the first response. Note: this is how it is implemented on the Prefixbox Portal Search Demo Tool.
- Alternatively you can render the new filters returned by the current API response.
Notes:
- The Hungarian names of the filters (DisplayName) will be specified from the Prefixbox Portal.
- The order of the Value Filters returned by Search API should be respected by the UX developer.
Recommendation for Search API response field selection:
You can get all the properties of the products. Typically you just want the Search API to return the list of Product Identifiers, and you can SELECT the rest of the product properties from your own SQL product database for these. It ensures that you have access to the latest product data, in case the Prefixbox Search Index might be out of sync. E.g.: there was a price or discount update for a few products.
What happens when Prefixbox Search API is down?
Prefixbox is hosted in two Azure data centers, and it can automatically fall back between the data centers when one of them has an availability issue. Because of this, service unavailability is a very rare event.
When the service is down: API response returns HTTP 50x error code.
You can decide to return your in-house search response or return a 0-result page, which contains the Prefixbox Navigation features, and save the user from a bad experience.
Developer requirements
Back-end developer
Estimated effort
3 days