tonita.search

tonita.search(query=None, listing_id=None, max_results=10, categories=None, facet_restrictions=None, retrieval_only=False, corpus_id=None, api_key=None, session=None)

Return search results given a query.

Parameters:

• query (Optional[str]) – The query for which relevant listings are retrieved. This query is a text string that specifies what the user is looking for, and is typically a keyword-search query or a natural-language query. If query is provided, listing_id must be None.

• listing_id (Optional[str]) – If listing_id is provided, a search will return listings that are similar to the given listing. If listing_id is provided, query must be None.

• max_results (int) – The maximum number of results to return.

• categories (Optional[List[str]]) – If given, search is restricted to listings within these categories.

• facet_restrictions (Optional[List[Dict[str, Any]]]) –

  If facet restrictions are provided, listings that satisfy more of the given restrictions will generally be ranked higher (and have higher scores) than listings that satisfy fewer of them. Each restriction is expressed as a dict with the following keys:

  1. ”name”: Required.

     The name of the facet. For example, “price”.

  2. ”type”: Required.

     The type of the facet across listings that the restriction is based on. This will determine how the facet value is handled (i.e., what operations are valid for it). For example, each listing may have a “price” facet that is numeric, or a “genre” facet that is a string.

     Valid values for this field are “STRING”, “NUMERIC”, and “BOOLEAN”.

  3. ”operation”: Required.

     The operation for the restriction. For example, if the value of some numeric facet must be greater than or equal to 9, the operation would be “GREATER_THAN_EQUAL”.

     Valid values are “EQUAL”, “LESS_THAN”, “LESS_THAN_EQUAL”, “GREATER_THAN”, “GREATER_THAN_EQUAL”, and “ONE_OF”.

  4. ”value”: Required.

     The value used for the restriction. Note that this is not necessarily the same as the facet value. For example, a restriction that movies must be one of three genres would have “value” be [“comedy”, “drama”, “thriller”], but the facet value for a movie that satisfies the restriction might just be “drama”. On the other hand, a restriction that the facet for “director” be “Jane Doe” would set the “value” field of the restriction to “Jane Doe”.

  5. ”weight”: Optional.

     An importance weight for the facet. This weight does not need to be normalized across facet restrictions. Weights must be provided either for all of the restrictions or for none of them. If no weights are provided, equal weights across restrictions will be assumed. Facets with zero or negative weight will be ignored. Consider the following example set of facet restrictions for books:

     [
         {
             "name": "pages",
             "type": "NUMERIC",
             "operation": "LESS_THAN_EQUAL",
             "value": 500,
             "weight": 3.14159,
         },
         {
             "name": "language",
             "type": "STRING",
             "operation": "ONE_OF",
             "value": ["english", "portuguese", "korean"],
             "weight": 2.71828,
         },
     ]
     

     Here, we have two restrictions: one that the number of pages of the book be less than 500, and one that the language of the book must be either English, Portuguese, or Korean. The importance weights denote that the restriction on the number of pages is slightly more important than the restriction on language.

• retrieval_only (bool) –

  Search progresses in two stages:

  1. A retrieval stage, where listings are retrieved along with raw

     scores;

  2. A rescoring stage, where we refine the scores of the listings

     that were retrieved.

  The retrieval stage is very fast, whereas the rescoring stage can take more time. Note, however, that the ranking of the listings will typically change after scores are refined. If this flag is set to True, only the retrieval phase will be performed and those results returned. If False, both phases will be performed.

  NOTE: At this time, the retrieval_only flag is applicable only for searches with a query, and its default value is False. For searches where a listing ID is specified, only raw scores will ever be returned. Therefore, the retrieval_only flag does not apply; richer rescoring options coming soon.

• corpus_id (Optional[str]) – The ID of the corpus to search within. If this argument is None, then the value of tonita.corpus_id will be used.

• api_key (Optional[str]) – An API key. If this argument is None, then the value of tonita.api_key will be used.

• session (Optional[requests.Session]) – A requests.Session object to use for the request. If the user does not provide a session, a new one will be created.

Returns:

See docstring for SearchResponse.

Return type:

SearchResponse

Raises:

• TonitaBadRequestError – The request is malformed; see error message for specifics.

• TonitaInternalServerError – A server-side error occurred.

• TonitaUnauthorizedError – The API key is missing or invalid.