904Labs Search API

This API documentation provides a description of 904Labs' Self-Learning Search service. We provide a high-level overview of the service on this page. We have a full example of how to implement our service on the Example page. The three endpoints each have their own page describing the details.

Prerequisites

  • Our service works on top of an existing search infrastructure. We currently support Apache Solr (with the Query Elevation Component enabled) and Elasticsearch. In case you are already using either of these two, we can connect to your own Apache Solr/Elasticsearch. This means that your data remains entirely yours, and that you don't need to change your web app to parse the search result format. To access your search infrastructure (Apache Solr or Elasticsearch), our REST app needs to be able to connect to your search engine. During the setup of the system we propose a way that suits your settings and requirements.

  • In case there is no existing search infrastructure available, we also offer a Cloud Indexing Service. This service allows you to have your index in the cloud, from where it can be used by 904Labs Self-Learning Search. For more details, see the indexing documentation.

  • We assume that a web app is present on the client side. This app communicates with our REST app and serves your website. Other than this, there are no prerequisites for using 904Labs Self-Learning Search service.

Workflow

904Labs Self-Learning Seach works with multiple consecutive calls from your web app to our REST app. Our REST app, in turn, makes several calls to the existing search engine (Apache Solr in this workflow diagram). In a common setup, the workflow consists of seven steps.

Workflow

Step Description
Step 1 A visitor searches your website and sends a text query to your web app.
Step 2 Your web app sends the visitor's text query to our spell checking endpoint. See GET /spellcheck for the request details.
Step 3 Our REST app communicates with your Apache Solr to find a suggested query.
Step 4 Our REST app returns a suggested query for the query to to your web app. See GET /spellcheck for the response details.
Step 5 Your web app sends the original or suggested text query to our search endpoint. See GET or POST /search for the request details.
Step 6 Our REST app communicates with your Apache Solr to construct a ranked list of items for the given query.
Step 7 Our REST app returns a modified sls query to your web app. See GET or POST /search for the response details.
Step 8 Your web app fires the sls query to an Apache Solr core endpoint that has the Query Elevation Component enabled (e.g., /elevate). It receives a ranked list of items in the same format as in the current situation.
Step 9 Your web app formats the ranked list and shows the results to the visitor. When the visitor interacts with the results (e.g., clicks, adds-to-basket), the web app records these feedback signals.
Step 10 Your web app sends the feedback signals to our feedback endpoint. See POST /feedback for the request details.
Step 10 In case a query has no results and a suggested query is present (in step 4), the web app should show a "Did you mean..." message to the visitor (see our Example). After clicking the suggested query, we go back to step 5.

904Labs provides three API endpoints to facilitate the workflow described above:

  • GET /spellcheck for spellchecking the original query and providing a suggested query.

  • GET or POST /search for ranking items based on the original or suggested query.

  • POST /feedback for sending visitors' feedback signals (e.g., clicks, add-to-basket).

Notes

  • Steps 2 to 4 are optional, although we recommend using them. Your web app could directly send the visitor's text query to the /search endpoint and receive a modified sls query.
  • The workflow mentions Apache Solr as search infrastructure. The wokflow for Elasticsearch is identical to the one above, where Apache Solr is replaced by Elasticsearch.
  • There is no need for caching of results. 904Labs SLS is using sophisticated caching strategies for serving requests as fast as possible. We take away processing load from your search infrastructure and move it to our own servers. This also speeds up response times by minimizing network traffic between your and our servers. Since caching is already in place, we strongly recommend not to use any caching on 904Labs' results at your end. First, it is very difficult to synchronize independent caches. Second, it leads to loosing important feedback from which 904Labs SLS learns.

More information

For more information and examples on how to implement our Self-Learning Search service, have a look at the Example page. In case of questions, please send an email to support@904labs.com