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:
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
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.
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)
“(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.
After calling our search API, the response returns in JSON format.
The response contains the following main parts:
The search results themselves and additional info.
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).
Note: there is a difference between the Id and the Identifier fields of the Document. Id is used by Prefixbox internally, and Identifier is the product identifier received from the customer’s product feed.
There are two types of facet 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.
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.
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.
RangeFilter.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.
RangeFilter.DisplayName (Filters.RangeFilters[i]. DisplayName) – String. A friendly name for the filter that can be displayed on the UI.
RangeFilter.Min (Filters.RangeFilters[i]. Min) – Number. The lower value of the filter.
RangeFilter.Max (Filters.RangeFilters[i]. Max) – Number. The upper value of the filter.
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.
ValueFilter.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.
ValueFilter.DisplayName (Filters.ValueFilters[i].DisplayName) – String. A friendly name for the filter that can be displayed on the UI.
ValueFilter.Values (Filters.ValueFilters[i].Values) – Array of ValueFilterValues.
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.
ValueFilterValue.Count (Filters.ValueFilters[i].Values[j].Count) – Number. The number of the current search results with the specified value.
ValueFilterValue.Value (Filters.ValueFilters[i].Values[j].Value) – String. A value by which the results can be filtered.
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.
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.
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.