Using the Fredhopper Query API

The following section details how you should format and send your query requests to the FAS service.

Overview

The basic concept is that the query string instructs FAS where the user is on the website, including any actions they have taken, and the response will confirm what items should be displayed. The recommended best practice is to use the HTTPS protocol to query the REST API endpoint and return a JSON-format response with gzip compression enabled.

Accessing the Fredhopper Query API

Fredhopper Managed Services provides query access via the following URL template - 'query.<configuration state>.<service instance>.<service>.<region>.fredhopperservices.com'. The URLs for your specific implementation will be given to you by your Technical Consultant. The query API supports access either via SOAP (WSDL) and REST (XML or JSON). It is important to note that each instance of FAS has a published and a pre-published configuration state, which are independent from each other. This allows the possibility to test and confirm different configurations on the pre-published environment before they are pushed to the published endpoint.

Please see the example endpoints below which will connect to the live1 instance of FAS for a customer in our EU1 region:

REST (XML/JSON)

Published Configuration

https://query.published.live1.fas.eu1.fredhopperservices.com/fredhopper/query

Pre-Published Configuration

https://query.prepublished.live1.fas.eu1.fredhopperservices.com/fredhopper/query

SOAP (WSDL)

Published Configuration

https://query.published.live1.fas.eu1.fredhopperservices.com/fredhopper-ws/services/FASWebService 

Pre-Published Configuration

https://query.prepublished.live1.fas.eu1.fredhopperservices.com/fredhopper-ws/services/FASWebService

The authentication of each request that is sent through is handled via HTTP Basic Access Authentication. Please see the 'Front-end Integration Tutorial' on the Crownpeak Support Centre for examples.

Fredhopper supports query access via the HTTP and HTTPS protocols. Please keep in mind that HTTPS adds an additional 50-100ms of latency to each query. For example, if a HTTP round-trip takes 400ms, then the same round-trip via HTTPS would take 450-500ms.

Compressed responses

Fredhopper's query API supports HTTP compression on the responses that are returned back to you web application. We strongly advise you to use HTTP compression since it reduces the network traffic by factor 10-15. In order to test this functionality, you can send a sample query request to the API that includes the required HTTP header for enabling a compressed response. See the example below that uses the wget command (note the HTTP header value in the request):

wget --header="Accept-Encoding: gzip" --user=<USERNAME> --password=<PASSWORD> https://query.published.live1.fas.eu1.fredhopperservices.com/fredhopper/query?fh_location=//catalog01/en_GB

Compression of the requests that are sent to Fredhopper is not supported on the Query API.

JSON-format responses

When using the REST endpoint, it is possible to receive the response back in JSON-format rather than an XML-format. The size of the JSON response is approximately 5% smaller than the same response in an XML-format and we strongly advise to enable JSON responses as per best practices. In order to test this functionality, you can send a sample query request to the API that includes the required HTTP header for enabling a JSON-format response. See the example below that uses the wget command (note the HTTP header values in the request):

wget --header="Accept-Encoding: gzip" --user=<USERNAME> --password=<PASSWORD> https://query.published.live1.fas.eu1.fredhopperservices.com/fredhopper/query?fh_location=//catalog01/en_GB