The front-end REST API is meant as a realtime link with your website, used for executing search queries, retrieving recommendations, and other functions.

Hosts

The frontend API endpoint is available on two different domains. They both offer the same functionality, but are different network-wise:

• gateway.tweakwisenavigator.com
  This endpoint contains a realtime failover load balancer that automatically falls back to another data center in case of a datacenter malfunction. This extra step in the network may increase request latency.
• gateway.tweakwisenavigator.net
  Using this endpoint, the client makes a direct connection with the closest data center, decreasing request latency. If there are problems in a data center, for example, hardware malfunction, traffic is automatically redirected to another datacenter. This redirect is based on DNS, so it may take a while before the redirect is functional everywhere.

We advise using 'gateway.tweakwisenavigator.net' as the primary endpoint and building in a failover in the code to ‘gateway.tweakwisenavigator.com’. Because the networks of these two endpoints are completely separate, we can guarantee a very high uptime.

If you would rather use one endpoint, we advise using ‘gateway.tweakwisenavigator.com’ instead of 'gateway.tweakwisenavigator.net'. That way, you will be less susceptible to delays in the DNS.

Instance key

Each request contains an instance key in the URL path. This instance key is a unique identification for a Tweakwise Navigator instance. You can find this key in Navigator at https://navigator.tweakwise.com/endpoint. The documentation clearly states where in the URL the instance key should be placed like /navigation-search/{instancekey}

Format

The API supports both XML and JSON. By default, a response is always returned in XML. If you'd rather use the JSON structure, you can expand the request using the query string parameter format=json. For example: https://gateway.tweakwisenavigator.com/autocomplete/{instanceKey}/?tn_q=shoes&format=json

API documentation

You can find the documentation on all the available endpoints here.

The documentation describes what the possible query string parameters are for each separate request and which parameters are required. You can also test a request by clicking the Try it out button. This gives you a clear idea of how the API behaves in your specific instance.

 

Grouping

Most calls are available in two versions: grouped and default. Here's an example in the autocomplete call:

The grouped version must be used when you use the grouping feature in Navigator.

What is a group code?

Which API calls should I use if I use group codes?

Navigation

The navigation endpoint allows you to fill a product lister page. The response consists of a few parts:

• List of facets
  These facets enable the end-user to filter on, for example, brand or color. An example of implementation:

• List of products
  The results also contain a list of products. These products are in line with the current filters and sorted by relevance in Navigator.
   
• An object that contains properties about the request
  This object contains information like the number of pages, number of products, and the sorting options.

You can find more information on the technical implementation on http://developers.tweakwise.com/api/#/Navigation

Navigation Search

Besides the navigation-call, there's a separate call for when a search term needs to be searched. This one is called navigation-search. The specifications are almost the same as the navigation call, apart from a few exceptions:

There is a possibility to send an extra search query-filter, the query string parameter: tn_q

The call returns an extra property about the request, suggestedsearchterm. When the user makes a typo in the search query, Navigator will replace the search query with the corrected version. It's possible to show the user that the search query has been replaced because we return this in the call. Example: