Skip to content

POST /search

904Labs A.I. for Search is transparent to your end application: once you send a text query to A.I. for Search, it will return a JSON response with a modified sls query that you use to retrieve results from your existing search engine. This guarantees that your web application receives exactly the same data format as it used to before switching to A.I. for Search. If, for any reason, A.I. for Search is unable to process a search request it will always return the original query for your search engine with the original arguments.

The /search endpoint works in five steps.

Diagram

Step Description
Step 1 Your web app sends the (original or suggested) text query to our /search endpoint.
Step 2 Our REST app processes the text query. The processed query is used to retrieve a set of candidate results from your Apache Solr (or Elasticsearch). Then, the REST app does its magic.
Step 3 Our REST app sends a modified sls query to your web app.
Step 4 Your web app sends the sls query to your Apache Solr (or Elasticsearch).
Step 5 Your Apache Solr (or Elasticsearch) sends the final list of results to your web app.

Request

HTTP request

POST https://api.904labs.com/sls/{customer_id}/search?q={query}&session_id={session_id}&user_id={user_id}&domain={domain}&locale={locale}&api_key={api_key}

Request attributes

Attribute Type Description
customer_id string (required) Your customer ID

Request parameters

Parameter Type Description
q string (required) The suggestion from POST /suggestion or the original query. URL encoded.
api_key string (required) Your API key.
session_id string (required) The session ID for the user issuing the query.
locale string (required) Country and language of the shop/site in ll_TT format, where ll is the language in ISO 639-1 format and TT is the territory in ISO 3166 format (e.g., en_US).
user_id string (optional) The user ID to allow for personalization of results.
domain string (optional) A particular domain to narrow the search (e.g., age group, subshop). (Default: default)
lang string (deprecated) Replaced by locale

Request body

Property name Value Description
baseline_query json (optional) Original query parameters that you use for your Apache Solr or Elasticsearch
filters json (optional) Filters that you use for your search engine
sort string (optional) Sort order that you use for your search engine (default is to sort by relevance)

Example requests

Consider a user who searches for "red carpet". You can either send this query directly to the search endpoint (as a text query) or construct your own baseline_query (i.e, your standard query parameters–we show an example for Apache Solr below) from it and send this baseline to the endpoint. Below, we show examples for both scenarios.

Without baseline

import requests as r

headers = {"content-type": "application/json"}
URL_SEARCH = "https://api.904labs.com/sls/CUSTOMER_ID/search"
params = {
    "q": "red carpet",
    "session_id": "SESSION_ID",
    "user_id": "USER_ID",
    "domain": "default",
    "locale": "en_US",
    "api_key": "APIKEY"
}

response = r.post(URL_SEARCH, headers=headers, params=params)

With baseline

import requests as r

headers = {"content-type": "application/json"}
URL_SEARCH = "https://api.904labs.com/sls/CUSTOMER_ID/search"
params = {
    "q": "red carpet",
    "session_id": "SESSION_ID",
    "user_id": "USER_ID",
    "domain": "default",
    "locale": "en_US",
    "api_key": "APIKEY"
}
payload = {
    "baseline_query": {
        "q": "red^2 carpet^5",
        "bq": "stock:[1 TO *]^10",
        "defType": "edismax",
        "fl": "id, title, score",
        "wt": "json"
    }
}

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

Response

{
    "sls_query": {
         ...
    },
    "search_id": string,
    "sls_on": boolean,
    "sort": string,
    "timestamp": int
}
Property name Value Description
sls_query json Query that is modified by A.I. for Search.
search_id string Unique identifier for this set of search results.
sls_on boolean Flag indicating whether A.I. for Search ran successfully (true) or not (false).
sort string Sorting property.
timestamp integer Current timestamp.

904Labs A.I. for Search returns a modified query sls_query that can directly be issued to your existing search engine. Issuing the sls_query to your search engine returns a search result set with documents from both A.I. for Search and (when present) your baseline_query. Documents returned from A.I. for Search are ranked at the top, followed by the documents retrieved by your existing search engine.

Apache Solr users

The sls_query must be sent to a Solr core endpoint that has the Query Elevation Component enabled, e.g., /elevate

In addition to the modified query, the response contains search_id, which is added to every returned document. search_id is used for sending feedback when users interact with the results, this way A.I. for Search knows to which query the feedback belongs; see POST /feedback.

Example response

{
    "sls_query": {
         "q": ["red^2 carpet^5"],
         "bq": ["stock:[1 TO *]^10"],
         "defType": ["edismax"],
         "elevateIds": ["document_id_456,document_id_148,document_id_23"],
         "enableElevation": ["true"],
         "fl": ["id,title,score,[elevated],search_id:[value v='667063374a170d531d02cbff5751695b']"],
         "sort": ["score desc"],
         "wt": ["json"]
    },
    "search_id": "667063374a170d531d02cbff5751695b",
    "sls_on": true,
    "sort": "score desc",
    "timestamp": 1469791146
}

When you issue sls_query to your existing search engine, you get a ranked_list of documents, namely, a list of search results for the query string you issued (here it was "red carpet"). Since this ranked_list comes from your own search engine, there is no change required in how the results are processed by your web application.

Avoid downtime

The final ranked_list comes from your own Apache Solr or Elasticsearch. This makes it possible to avoid any downtime to your site search caused by 904Labs. To do this, you can add a time-out to the calls to the 904Labs REST app. When our service does not respond within the given time, you can fallback to sending your baseline_query directly to your Apache Solr or Elasticsearch.

Python example

import requests as r

headers = {"content-type": "application/json"}
URL_SEARCH = "https://api.904labs.com/sls/CUSTOMER_ID/search"
params = {
    "q": "red carpet",
    "api_key": "APIKEY",
    "session_id": "SESSION_ID",
    "user_id": "USER_ID",
    "domain": "default",
    "locale": "en_US"
}
payload = {
    "baseline_query":{
        "q": "red^2 carpet^5",
        "bq": "stock:[1 TO *]^10",
        "defType": "edismax",
        "fl": "id, title, score",
        "wt": "json"
    },
    "sort": "score desc"
}

your_payload = {}

try:
    response = r.post(URL_SEARCH, json=payload, headers=headers, params=params, timeout=1)
    response = response.json()

    your_payload = response["sls_query"]
except r.exceptions.Timeout:
    ## The server does not respond within 1 second
    ## Use the baseline query to fetch final ranked list
    your_payload = payload["baseline_query"]


## Get results from your _own_ Solr core or Elasticsearch
## For Solr, use an endpoint with QueryElevation enabled

YOUR_SEARCH_ENDPOINT = "https://YOUR_SOLR_CORE" + "/elevate" 

## Get results from your search engine with re-ranked documents or with baseline query in case of time-out
response = r.post(YOUR_SEARCH_ENDPOINT, json=your_payload, headers=headers)