API Reference

Note: When implementing search using REST API, you need to report clicks made by users to the following endpoint. Information about users’ clicks is required for detailed analytics reports. It also allows AddSearch to apply progressive ranking which improves the search results relevancy.

GET /v1/search/{index public key}

Retrieve search results from the index.

Required Query Parameter

Parameter	Description	Type
term	Search term, also known as the keyword. Use * to get all search results instead	string

Optional Query Parameters

Parameter	Description	Type	Notes
limit	The number of results to return per page	int	Must be between 1 and 300. The default is 10.
page	The number of the paginated result page to return	int	The default is 1.
jsonp	JavaScript function call wrapped around the response JSON	string	JSONP (JSON with Padding) is used for sending JSON data which helps to resolve cross-domain issues. By default, all results are returned.
lang	Limit results to a specific language	string	Should be in two-letter language format, e.g. “en”, “de”, “es”. For more information, visit the documentation. By default, all results are returned.
categories	Limit results to a domain, URL path, or filetype	string	For more information, visit the documentation on the categories. Example of categories parameter. By default, all results are returned.
sort	Return results sorted by relevance, date, or custom field names	string	Valid values: “relevance”, “date” or a name of a custom field e.g. custom_fields.average_rating. The default is “relevance”.
order	Return results sorted by date or custom fields in ascending or descending order	string	Valid values: “desc” or “asc”. Applicable if “sort=date” or "sort=customField". The default is “desc”.
fuzzy	Matches words that are close to the search terms	string	Valid values: “false” (disabled), “true” (enabled), or “auto” (automatic). The suggested value is “auto.” The default is “false”.
postfixWildcard	Adds a wildcard at the end of the search term and is ideal for the search-as-you-type feature	boolean	Set it to false if you want to emphasise exact matches (you will get less results and better highlights). The default is true.
dateFrom	Return only results that are newer than the specified date	string	The format is yyyy-mm-dd (example: 2020-11-01). By default, all results are returned.
dateTo	Return only results older than the specified date	string	The format is yyyy-mm-dd (example: 2020-11-01). By default, all results are returned.
customField	Return only results containing the specified custom field and value pair	string	The format is “key=value” and the format in query parameter needs to be URL encoded e.g. key%3Dvalue. If the same custom field name is given with different values, results with any value will be returned (i.e. OR match). If multiple custom field names are defined, results must match each criterion. For more information, visit the documentation. Example of customField parameter. By default, all results are returned.
resultType	Return only results with- or without Pinned results and Promotions	string	Valid values: “all” and “organic” (results without Pinned results or Promotions). The default is “all”.
userToken	User token for search personalization	string	By default, all results are returned.
facet	Return categories where the search results belong to	string	Pass one or more custom fields to receive facets from specified fields. Example of facet parameter. By default, no facets are returned.
numFacets	Limit the maximum number of aggregations returned for each field defined with facet parameter	int	The maximum value is 1000. The default is 10.
rangeFacets	Group numerical custom fields into ranges	object	Example of rangeFacets parameter. By default, no facets are returned.
collectAnalytics	Specifies if the search event is added to the statistics shown in the Dashboard	boolean	The default is true.
analyticsTag	A tag that can be used to filter analytics in the dashboard. For more information read the article.	string	The maximum length of a tag is 50 characters.
filter	Filter object that uses custom_fields values for filtering search results.	object	Supports nested and, or, not, and range filters. Examples of filter parameters.
defaultOperator	When a user searches with multiple keywords, we return only documents that contain all the terms which means applying the logical operator AND for the query. It is possible to choose which logical operator to use for fuzzy results when the fuzzy parameter is set to auto.	string	There are two options: "or": makes fuzzy results broader and includes partial matches of a few search terms "and": makes fuzzy results stricter and includes only mistyped search terms

Example of categories parameter

The URL www.example.com/news/article.pdf has category properties 0=www.example.com, 1=some, and doctype_pdf.

&categories=0xwww.example.com returns results from www.example.com, &categories=1xnews returns results from /news/ and &categories=doctype_pdf returns results with filetype pdf.

Example of customField parameter

The custom fields “city=London” AND “genre=rock” OR “genre=pop” with URL encoding:

&customField=city%3Dlondon&customField=genre%3Drock&customField=genre%3Dpop

&facet=custom_fields.genre&facet=custom_fields.artist returns search result aggregations by genre and artist custom fields.

&facet=categorys&categories=1xblog returns search result aggregations by blog category.

[
    {
      "field": "custom_fields.price",
      "ranges": [
          { "to": 10 },
          { "from": 10, "to": 20 },
          { "from": 20 }
        ]
    }
]