904Labs Self-learning Search API

This API documentation provides a description of the workflow of 904Labs Self-learning Search (SLS) to get a high-level understanding of the service. We also describe the three actual API endpoints for query spellchecking, searching, and sending feedback.

904Labs SLS supports the following popular open-source search engines:

Workflow

To give a high-level understanding of 904Labs SLS, we provide a short description of its workflow. We use the schema below to go through the workflow step by step.

Diagram

As the schema shows, there are several points of interaction from or to the system with the search box (usually a website).

  1. The query entered by the visitor can be submitted to 904Labs spellchecking, which provides spellchecks for the query. This step is optional, but in case it is included, it is recommended to use the spellcheked query.

  2. The (original or spellchecked) query is send to our 904Labs SLS, which results in a response containing a so-called sls query. This modified query is the result of applying our self-learning algorithms to the original query and, optionally, the client's engine specific parameters.

  3. The sls query can then be submitted directly to the client's existing search engine, resulting in a ranked list of documents. These are the search results that are displayed on the website. Since the final results are retrieved from the existing search engine, there is no need to change the way the ranked list is processed by the website.

  4. Once the visitor starts interacting with the search results, for example by clicking or adding to her basket, these feedback signals are submitted to 904Labs SLS. Feedback is what is used to make the system self learning.

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

Full code example

The code example below is an implementation of 904Labs SLS, including spellchecking. Please read the documentation of the individual endpoints for more details.

import requests as r

headers = {'content-type': "application/json"}

# Spellcheck
URL_INIT_SEARCH = "https://api.904labs.com/sls/CUSTOMER_ID/spellcheck"
params = {
    "q":"red capret",
    "user_id":"1",
    "api_key":"APIKEY"
}
response = r.post(URL_INIT_SEARCH, headers=headers, params=params)
response = response.json()


# Obtain SLS_query

URL_SEARCH = "http://api.904labs.com/sls/CUSTOMER_ID/search"
params = {
    "q":"red carpet",
    "api_key":"APIKEY",
    "session_id":"1A",
    "user_id":"1",
    "domain":"default"
}
payload = {
    "baseline_query":{
        "q": "red^2 carpet^5",
        "bq": "stock:[1 TO *]^10",
        "defType": "edismax",
        "fl": "id, title, score",
        "wt": "json"
    },
    "sort": "score desc"
}
response = r.post(URL_SEARCH, json=payload, headers=headers, params=params)
response = response.json()

# Obtain search_id
SEARCH_ID = response['search_id']

# Get results from your _own_ Solr core or Elasticsearch
YOUR_SEARCH_ENDPOINT = "http://YOUR_SOLR_CORE" + "/elevate" 
payload = response["sls_query"]
response = r.post(YOUR_SEARCH_ENDPOINT, json=payload, headers=headers)
response = response.json()


# Send feedback to SLS

FEEDBACK_URL = "https://api.904labs.com/sls/CUSTOMER_ID/feedback/" + SEARCH_ID
params = {"api_key":"APIKEY"}
payload = {
    "document_id_148": "CLICK",
    "document_id_456": "PURCHASE"
}

response = r.post(FEEDBACK_URL, json=payload, headers=headers, params=params)