search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Search

The search API allows you to search over, facet, and filter your data. The Search Guide has plenty of examples and information to get you started.

POST /api/as/v1/engines/{ENGINE_NAME}/search
query
required
A string or number used to find related documents. To match all documents, use an empty string "".
search_fields
optional
A dictionary containing field names as keys and search field options as values. Defaults to searching over all text fields with equal importance. For more information, see the search fields section and weights section in the Search Guide.
boosts
optional
A dictionary containing field names as keys and boost options as values. Defaults to no boosting (i.e. the document score will only be based on the text matching score).
group
optional
A dictionary containing the field to group on and an optional size and sort argument. Defaults to no grouping, and the _group key will not be present in the returned documents. For more information, see the grouping section in the Search Guide.
result_fields
optional
A dictionary containing field names as keys and result field options as values. Defaults to returning raw values of all fields. For more information, see the result fields section in the Search Guide.
facets
optional
A dictionary containing field names as keys and facet options as values. Defaults to requesting no facets. For more information, see the facets section section in the Search Guide.
sort
optional
A dictionary or list of dictionaries representing sort options: single key-value dictionary with the key being a {field_name} or "_score" and the value being sort the sort direction ("asc" or "desc"). Defaults to sorting by descending score (i.e. { "_score": "desc"}). For more information, see the sorting section in the Search Guide.
page
optional
A dictionary with optional keys of size and current. Specifies the number of results per page and which page the API should return. For more information, see the paging section in the Search Guide.
analytics
optional
A dictionary containing the key tags, an array of strings representing additional information you wish to track about the query. You can then filter queries by these tags in the Analytics tab of the App Search dashboard. For more information, see the analytics section in the Search Guide.

Fields in the API Response

Upon a successful API request the following keys can be present in the response. If there are any errors processing your query, a 400 response will be returned.

results

Always present in API response upon a successful query. It will be a list of documents that match the requested query and filters. The returned fields of the document are specified by result_fields and can have a "raw" and/or "snippet" value. By default all fields are returned in the "raw" format.

meta

Always present in API response upon a successful query. It will be a dictionary containing information about the result set.

pageA dictionary with keys size (number of results per page), current (page number that is in the results field), total_results (number of results that match the query), and total_pages (number of of results available).

facets

Only present when the request provides the facets parameter. It will be a dictionary with the key being the field name and the value as a list of facet results in the following format.

typeType of facet requested and subesquently returned.
valuesA list of dictionaries containing information about the facet. Each dictionary will have a count key with a value that represents the number of documents that belong to that facet. A value facet will have a value key with a value of the actual document value being counted; a range facet will have a from and to key representing the range the facet covers.

Common Malformed API Requests

There are many ways that a query request can fail. The error message returned by the API will have detailed information regarding what should be changed to ensure a successful request and will return a 400 response.

parameterConditions of when a 400 response will be returned by the API
queryIf the parameter is missing from the request.
If the parameter value is not a string or a number.
search_fieldsIf a requested search field does not exist in the current schema.
If a search field object is malformed. It must be an empty dictionary or a dictionary with a key of "weight".
If all search fields are non-text fields.
result_fieldsIf a result field requested does not exist in the current schema.
If a request field object is malformed. It must be an empty dictionary or have keys of "raw" and/or "snippet" and a value of a dictionary optionally containing keys of "size" and "fallback" (if requesting a snippet).
If the requested raw size is less than 15.
If a size is requested for a non text field.
If the requested snippet size is not greater or equal to 20 and less than 1000.
If the fallback parameter for a snippet is not a boolean.
facetsIf the faceting field is not in the schema.
If the requested facets object is malformed.
If a value facet is on a field type that is not text, number, or date.
If a range facet is on a field type that is not number, date, or geo.
If a range facet does not provide ranges in an acceptable format for the field type.
boostsIf the boosted field is not in the schema.
If the boost object is malformed, missing required arguments, or has invalid values.
If a value boost is not on a field type that is not text, number, or date.
If a functional boost is on a field type that is not number.
If a proximity boost is on a field type that is not number, date, or geo.
sortIf the field used to sort is not in the schema and is not "_score".
If the sort object has more than one key.
pageIf the parameter is not a dictionary.
If the size argument is not greater than or equal to 1 and less than 1,000.
If the page argument is not greater than or equal to 1 and less than 500.