Sign in

v1

latestOpenAPI 3.0.22026-08-0426137631.3 KB
Q&A APIs

Q&A API

Question Answering API analyzes each Product's html field and extracts paragraphs that can answer users' questions.

For example, Miso can take question likes What is python?, and extract an answer like Python is an interpreted, object-oriented, high-level programming language. from a product's html field.

Each answer is assigned a probability score that determines how likely a paragraph can accurately answer the question. A probability at least 0.7 is recommended, but you usually will need to fine-tune this threshold to find the precision-and-recall sweet-spot for your application.

Limitations

Miso will only extract answers from the html field and from products that have enable_question_answering set to true. Also, since Q&A is a much more complex search problem, the response time of this API is usually between 1 to 2 seconds for a new question. For an old question this API has answered before, the response time will be less than 75ms.

post/v1/qa/question_answering

Request body

version'v1.2' | 'v1.3'

The model version to use.

  • v1.2: First stable version
  • v1.3: Improve keyword extraction that make answers more precise
qstring required

The question user has entered.

min_probabilitynumber required

Minimum acceptable probability (between 0.0 and 1.0). The answers whose probability is lower than this number will be excluded from the response.

rowsinteger

Number of search results to return.

flstring[]

List of fields to retrieve. Each Q&A response, by default, return two fields answer and product_id, where answer is an object with the information about the answer paragraph while product_id identifies the Product from which the answer is extracted.

For example, the following is a sample response from the API:

{
 "product_id": "ABC-123",
 "answer":
  {
   "html": "<p>Python is an interpreted programming language</p>",
   "text": "Python is an interpreted programming language",
   "css_selector": ":root > div:nth-child(1) > p:nth-child(2)",
   "probability": 0.99
  }
}

You can use fl parameter to retrieve additional product fields. For example, the following request additionally retrieves the title field for each product along with the product_id and answer, which are always returned.

{"fl": ["title"]}

You can also match field names by using * as a wildcard. For example, the query below retrieves the title and all the custom_attributes fields.

{"fl": ["title", "custom_attributes.*"]}

The following request retrieves all the available product fields:

{"fl": ["*"]}

For the lowest latency, use an empty array (which is the default) to retrieve just the product_id and answer fields.

{"fl": []}
enable_answer_htmlboolean

Whether to return HTML of the answer paragraph. If you don't need the HTML content of the answer paragraph, setting this parameter to false will reduce the response size and lower the response latency.

enable_answer_blockboolean

Whether to return answer block. In addition to answer paragraph, Miso can additionally return answer block. Answer block is an ancestor HTML node of the answer paragraph that contains the relevant context. The answer block is particularly useful for applications that not only want to show the answer itself but also the context surrounding the answer.

Answer block is the smallest HTML element that contains the relevant context. However, not all the content inside this node is relevant. You can use the returned relevant_children_slice field to identify a portion of this node that is relevant to the answer.

fqstring

Defines a query in Solr syntax that can be used to restrict the superset of products to return, without influencing the overall ranking. fq can enable users to drill down to products with specific features based on different product attributes

For example, the query below limits the search results to only show products whose size is either M or S and brand is Nike:

{"fq": "size:(\"M\" OR \"S\") AND brand:\"Nike\""}

You can use fq to apply filters against your custom attributes as well. For example, the query below limits the search results to only products whose designer attribute is Calvin Klein

{"fq": "attributes.designer:\"Calvin Klein\""}

fq can also limit search results by numerical range. For example, the following query limits the results to products that have rating >= 4.

{"fq": "rating:[4 TO *]"}
boost_fqstring

Defines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to specific boost positions (See boost_positions parameter below.) For example, the query below will promote all the relevant products whose brand is Nike to the top of recommendation list:

{
    "boost_fq": "brand:\"Nike\""
}

For a slightly more complex example, the query below will promote the Nike products which have also been tagged as ON SALE to the top of the ranking:

{
   "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\""
}

It is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert, and will not boost a low performance product only because it matches the boosting query.

Depending on your boosting rules, in certain cases, you would like to prevent recommendation results from being too monotone due to boosting. With Miso, you have two tools to do so.

First, you can specify boost_positions to place promoted products at specific positions in the ranking. For example, the query below will place boosted products only at the first and fourth places in the ranking (positions are 0-based), and place the remaining products in their original ranking, skipping these two positions.

{
   "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"",
   "boost_positions": [0, 3]
}

The second tool is diversification. diversification parameter, on a best-effort basis, will try to maintain a minimum distance between products that have the same attributes. For example, the following query will place products made by the same brand apart from each other.

{
   "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"",
   "diversification": {
       "brand": {"minimum_distance": 1}
    }
}
boost_positionsinteger[]

Defines a list of 0-based positions you want to place the boosted products at.

For example, the query below will promote products whose brand is Nike as the top and second recommendations:

{
    "boost_fq": "brand:\"Nike\"",
    "boost_positions": [0, 1]
}

If boost_positions is not specified (which is the default behavior), all the boosted products will be ranked higher than the rest of the products.

boost_rule_namestring

Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response

boost_probability_thresholdnumber

Minimum probability required for an answer to be boosted. If not specified, the min_probability will be used.

Example request

{
  "version": "v1.2",
  "q": "what is gradient descent",
  "min_probability": 0.7
}

Response

Successful Response

messagestring

Example response

{
  "data": {
    "miso_id": "123e4567-e89b-12d3-a456-426614174000",
    "total": 1000,
    "spellcheck": {
      "original_query": "what is pythn",
      "original_query_with_markups": "what is <mark>pythn</mark>",
      "corrected_query": "what is python",
      "corrected_query_with_markups": "what is <mark>python</mark>"
    }
  }
}