Skip to content

POST /browse

904Labs A.I. for Search is transparent to your end application: once you send a category to A.I. for Search's browse endpoint, it will return a JSON response with a modified sls query that you use to retrieve results from your existing search index. 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 browse request it will always return the original category with the original arguments.

The /browse endpoint works in five steps.

Diagram

Step Description
Step 1 Your web app sends the category to our /browse endpoint.
Step 2 Our REST app retrieves category items 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 items in the category to your web app.

Request

HTTP request

POST https://api.904labs.com/sls/{customer_id}/browse?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
api_key string (required) Your API key.
session_id string (required) The session ID for the user browsing.
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 browse (e.g., age group, subshop). (Default: default)
skip_sls boolean (optional) Indicates whether or not to apply our trained ranking functions for this request. Used in combination with the sort parameter. When set to true, items in the category are sorted purely by the sort parameter. When set to false, the first 100 items are ranked by our system and the remaining items in the category are sorted by the sort parameter. (Default: false)

Request body

Property name Value Description
filters json (required) Filters that you use for your categories
sort json (required) Sort order that you use for your category. See skip_sls above for details.

Example requests

Consider a user who browses the "chairs" category. To receive an optimized product listing for this category, you send your current filter query (as filters) and sorting parameter (as sort) to the endpoint. Below, we show an example where products are returned for the "chairs" category that are sorted in ascending order by price (before optimization).

import requests as r

headers = {"content-type": "application/json"}
URL_SEARCH = "https://api.904labs.com/sls/CUSTOMER_ID/browse"
params = {
    "session_id": "SESSION_ID",
    "user_id": "USER_ID",
    "domain": "default",
    "locale": "en_US",
    "api_key": "APIKEY"
}
payload = {
    "filters": {
        "fq": ['cat:"chairs"'],
        "bf": ["rating^8 boost"],
        "bq": ["(!type:secondhand)^2"]
    },
    "sort": "price asc"
}

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 items.
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 product listing which is optimized by A.I. for Search. Documents that A.I. for Search deems most "relevant" are ranked at the top (using elevatedIds in Solr or function_score in Elasticsearch), followed by the documents sorted by your current sorting parameter.

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 items in the category, this way A.I. for Search knows to which request the feedback belongs; see POST /feedback.

Example response

{
    "sls_query": {
         "fq": ['cat:"chairs"'],
         "bf": ["rating^8 boost"],
         "bq": ["(!type:secondhand)^2"],
         "elevateIds": ["document_id_456,document_id_148,document_id_23"],
         "enableElevation": ["true"],
         "fl": ["id,title,score,[elevated],search_id:[value v='667063374a170d531d02cbff5751695b']"],
         "sort": ["price asc"],
         "wt": ["json"]
    },
    "search_id": "667063374a170d531d02cbff5751695b",
    "sls_on": true,
    "sort": "price asc",
    "timestamp": 1469791146
}

When you issue sls_query to your existing search engine, you get a ranked_list of documents, namely, a list of items matching the filter query you issued (here it was "chairs"). Since this ranked_list comes from your own search engine, there is no change required in how the items 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 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 filters 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/browse"
params = {
    "session_id": "SESSION_ID",
    "user_id": "USER_ID",
    "domain": "default",
    "locale": "en_US",
    "api_key": "APIKEY"
}
payload = {
    "filters": {
        "fq": ['cat:"chairs"'],
        "bf": ["rating^8 boost"],
        "bq": ["(!type:secondhand)^2"]
    },
    "sort": "price asc"
}

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["filters"]


## 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)