Search Results API

Use the AddSearch REST API to retrieve search results from your search index. This endpoint returns results in JSON format with flexible filtering, sorting, and pagination options.

Note: When you implement search using this API, you must report user clicks to the Report User Event endpoint. Click data enables detailed analytics reports in the Analytics Dashboard and allows AddSearch to improve result relevancy through progressive ranking.

HTTP Request

GET /v1/search/{index_public_key}

Replace {index_public_key} with your site's public API key (SITEKEY). Do not use your secret API key here.

---

Required Query Parameter

Parameter	Description	Type
term	Search term (keyword). Use * to retrieve all results.	string

---

Optional Query Parameters

Parameter	Description	Type	Notes
limit	Number of results per page	integer	1–300, default 10
page	Page number for pagination	integer	Default is 1
jsonp	Wraps JSON response in a JavaScript function call (JSONP)	string	Used for cross-domain requests. When omitted, response is pure JSON.
lang	Limit results to a specific language	string	Use two-letter codes (e.g., "en", "de", "es"). See Language Documentation. Default returns all languages.
categories	Filter results by domain, URL path, or file type	string	See Category Filters. Example below. Default returns all categories.
sort	Sort results by "relevance", "date", or a custom field (e.g., custom_fields.average_rating)	string	Default is "relevance"
order	Sort order: ascending (asc) or descending (desc)	string	Applies when sorting by date or custom fields. Default is "desc"
fuzzy	Enable fuzzy matching to find approximate matches	string	"false" (disabled), "true" (enabled), or "auto" (automatic). Recommended default is "auto". Default is "false" (verify this).
postfixWildcard	Append wildcard to the end of search term (useful for search-as-you-type)	boolean	Default true. Set to false for stricter exact matches and fewer highlights.
dateFrom	Return results newer than this date (format: yyyy-mm-dd)	string	Default includes all dates
dateTo	Return results older than this date (format: yyyy-mm-dd)	string	Default includes all dates
customField	Filter results by custom field with key=value pairs, URL-encoded	string	Multiple values for the same key perform an OR match; multiple keys perform AND. See Using Custom Fields and example below.
resultType	Return all results or only organic (exclude pinned/promotions)	string	"all" (default) or "organic"
userToken	Token for personalized search results	string	Optional
facet	Return aggregation counts for specified fields	string	Pass one or more fields for faceting. See example below. Default: no facets returned.
numFacets	Maximum number of facet aggregations per field	integer	Max 1000, default 10
rangeFacets	Group numerical custom fields into specified ranges	object	JSON object describing ranges. See example below. Default: no range facets.
collectAnalytics	Include this search event in Analytics Dashboard statistics	boolean	Default true.
analyticsTag	Tag string for filtering analytics reports	string	Max 50 characters. See Analytics Tags for details.
filter	Complex filter object using custom_fields, supporting AND, OR, NOT, and range filters	object	Supports nested logic. See examples below.
defaultOperator	Logical operator for multi-word fuzzy queries: "or" or "and"	string	Applies when fuzzy=auto. "or" broadens matches (partial terms), "and" restricts to mistypes only.

---

Examples

Categories Parameter

For the URL www.example.com/news/article.pdf, the categories are:

• 0=www.example.com
• 1=news
• doctype_pdf

Use these to filter results:

Parameter	Returns results from
&categories=0xwww.example.com	The entire domain www.example.com
&categories=1xnews	The /news/ path
&categories=doctype_pdf	Documents with PDF filetype

Custom Field Parameter

To return results where city is London AND genre is rock OR pop:

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

(Values must be URL-encoded; = becomes %3D.)

Facet Parameter

To get aggregations of search results by custom fields genre and artist:

&facet=custom_fields.genre&facet=custom_fields.artist

To get aggregations by blog category:

&facet=categorys&categories=1xblog

Range Facets Parameter

Group custom_fields.price into ranges:

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

URL-encoded as:

rangeFacets=%5B%7B%22field%22%3A%20%22custom_fields.price%22%2C%22ranges%22%3A%20%5B%7B%22to%22%3A10%7D%2C%7B%22from%22%3A10%2C%22to%22%3A20%7D%2C%7B%22from%22%3A20%7D%5D%7D%5D

Filter Parameter

Return results with price between 10000 and 20000:

{
  "range": {
    "custom_fields.price": {
      "gt": "10000",
      "lt": "20000"
    }
  }
}

URL-encoded:

filter%3D%7B%22range%22%3A%7B%22custom_fields.price%22%3A%7B%22gt%22%3A%2210000%22%2C%22lt%22%3A%2220000%22%7D%7D%7D

Return results where brand is apple, color is not white, and price is between 200 and 500:

{
  "and": [
    { "custom_fields.brand": "apple" },
    { "not": { "custom_fields.color": "white" } },
    { "range": { "custom_fields.price": { "gt": 200, "lt": 500 } } }
  ]
}

URL-encoded:

filter%3D%7B%22and%22%3A%5B%7B%22custom_fields.brand%22%3A%22apple%22%7D%2C%7B%22not%22%3A%7B%22custom_fields.color%22%3A%22white%22%7D%7D%2C%7B%22range%22%3A%7B%22custom_fields.price%22%3A%7B%22gt%22%3A200%2C%22lt%22%3A500%7D%7D%7D%5D%7D

Return results from example.com domain and /blog/ path:

{
  "and": [
    { "category": "0xexample.com" },
    { "category": "1xblog" }
  ]
}

URL-encoded:

%7B%22and%22%3A%5B%7B%22category%22%3A%220xexample.com%22%7D%2C%7B%22category%22%3A%221xblog%22%7D%5D%7D

Return results where custom_fields.manufacturer matches any case variation of "nokia":

{
  "and": [
    {
      "or": [
        { "custom_fields.manufacturer": "nokia" },
        { "custom_fields.manufacturer": "Nokia" },
        { "custom_fields.manufacturer": "NOKIA" }
      ]
    }
  ]
}

URL-encoded:

%7B%22and%22%3A%5B%7B%22or%22%3A%5B%7B%22custom_fields.manufacturer%22%3A%22nokia%22%7D%2C%7B%22custom_fields.manufacturer%22%3A%22Nokia%22%7D%2C%7B%22custom_fields.manufacturer%22%3A%22NOKIA%22%7D%5D%7D%5D%7D

---

Sample Request

GET https://api.addsearch.com/v1/search/cfa10522e4ae6987c390ab72e9393908?term=rest+api

---

Sample Response

{
  "page": 1,
  "total_hits": 1,
  "processing_time_ms": 21,
  "hits": [
    {
      "id": "54f5b92d4e4766f4bc0ce2b05f80f58d",
      "thumbnail_external_src": "https://www.example.com/thumbnail-image.jpg",
      "url": "https://www.addsearch.com/developers/api/",
      "title": "AddSearch REST API",
      "meta_description": "Documentation of our REST API",
      "meta_categories": ["features", "api"],
      "custom_fields": {
        "location": "London",
        "genre": ["Rock", "Pop"]
      },
      "highlight": "AddSearch’s REST API provides programmatic access to your search index",
      "ts": "2015-01-22T11:56:10",
      "categories": [
        "0xwww.addsearch.com",
        "1xdevelopers",
        "2xapi"
      ],
      "document_type": "html",
      "images": {
        "main": "https://d20vwa69zln1wj.cloudfront.net/1bed1ffde465fddba...",
        "main_b64": "/9j/4AAQSkZJRgABAQIAHAAcAAD/2wBDACgcHiMeGSgjISMtKygwPG...",
        "capture": "https://d20vwa69zln1wj.cloudfront.net/1bed1ffde465fddba..."
      },
      "score": 0.790107
    }
  ],
  "facets": null,
  "rangeFacets": null
}

---

Returned Fields Description

• page: Requested page number
• total_hits: Total number of matching documents
• processing_time_ms: Time in milliseconds to process the request
• hits: Array of matched documents

Each document in hits contains:

Field	Description	Type
id	Document identifier	string
thumbnail_external_src	URL of thumbnail image	string (URL)
url	Document URL	string
title	Document title	string
meta_description	Document meta description (nullable)	string or null
meta_categories	Document meta categories (nullable)	array of strings or null
custom_fields	Custom metadata fields	object with string or array values
highlight	Search term matching text snippet	string
ts	Publish date/time (ISO 8601 format)	string
categories	Automatic categories like domain or filetype	array of strings
document_type	Document type: html, pdf, docx, pptx, etc.	string
images	Images object with thumbnail and captures	object
images.main	Thumbnail image URL (nullable)	string or null
images.main_b64	Base64 encoded low-res thumbnail (nullable)	string or null
images.capture	URL for screen capture image (nullable)	string or null
score	Relevance score for the document	number
facets	Aggregation data for facets (nullable)	object or null
rangeFacets	Numerical range aggregations (nullable)	object or null

---

Query Limits

The term parameter supports:

• Maximum length: 300 characters
• Maximum number of words: 20

---

Related API Endpoints

• Search Suggestions API to provide autocomplete suggestions.
• Report User Event API to send search and click analytics for better insights.

---

For detailed information on filtering, faceting, and custom fields, refer to the linked documentation sections within this article.