GET /v1/search/{index public key}

Retrieve search results from the index.

Required Query Parameter

ParameterDescriptionType
termSearch term, also known as the keywordstring

Optional Query Parameters

ParameterDescriptionTypeNotes
limitThe number of results to return per pageintMust be between 1 and 300.

The default is 10.
pageThe number of the paginated result page to returnintThe default is 1.
jsonpJavaScript function call wrapped around the response JSONstringJSONP (JSON with Padding) is used for sending JSON data which helps to resolve cross-domain issues.

By default, all results are returned.
langLimit results to a specific languagestringShould be in two-letter language format, e.g. “en”, “de”, “es”.

For more information, visit the documentation.

By default, all results are returned.
categoriesLimit results to a domain, URL path, or filetypestringFor more information, visit the documentation on the categories and meta categories.

Example of categories parameter.

By default, all results are returned.
sortReturn results sorted by relevance, date, or custom field namesstringValid values: “relevance”, “date” or a name of a custom field e.g. custom_fields.average_rating.

The default is “relevance”.
orderReturn results sorted by date or custom fields in ascending or descending orderstringValid values: “desc” or “asc”. Applicable if “sort=date” or "sort=customField".

The default is “desc”.
fuzzyMatches words that are close to the search termsstringValid values: “false” (disabled), “true” (enabled), or “auto” (automatic). The suggested value is “auto.”

The default is “false”.
postfixWildcardAdds a wildcard at the end of the search term and is ideal for the search-as-you-type featurebooleanSet it to false if you want to emphasise exact matches (you will get less results and better highlights).

The default is true.
dateFromReturn only results that are newer than the specified datestringThe format is yyyy-mm-dd (example: 2020-11-01).

By default, all results are returned.
dateToReturn only results older than the specified datestringThe format is yyyy-mm-dd (example: 2020-11-01).

By default, all results are returned.
customFieldReturn only results containing the specified custom field and value pairstringThe 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.
resultTypeReturn only results with- or without Pinned results and PromotionsstringValid values: “all” and “organic” (results without Pinned results or Promotions).

The default is “all”.
userTokenUser token for search personalizationstringBy default, all results are returned.
facetReturn categories where the search results belong tostringPass one or more custom fields to receive facets from specified fields.

Example of facet parameter.

By default, no facets are returned.
numFacetsLimit the maximum number of aggregations returned for each field defined with facet parameterintThe maximum value is 100.

The default is 10.
rangeFacetsGroup numerical custom fields into rangesobjectExample of rangeFacets parameter.

By default, no facets are returned.
collectAnalyticsSpecifies if the search event is added to the statistics shown in the DashboardbooleanThe default is true.

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

Examples of facet parameter

&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.

Example of rangeFacets parameter

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

The parameter needs to be URL-encoded

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

Please note that the Search API uses your public SITEKEY, not the secret API key!

Sample Request

https://api.addsearch.com/v1/search/1bed1ffde465fddba2a53ad3ce69e6c2?term=rest+api

Response

{
  "page": 1,
  "total_hits": 1,
  "processing_time_ms": 21,
  "hits": [
    {
      "id": "54f5b92d4e4766f4bc0ce2b05f80f58d",
      "url": "https://www.addsearch.com/developers/api/",
      "title": "AddSearch REST API",
      "meta_description": "Documentation of our REST API",
      "meta_categories": ["features", "api"], // <meta name="addsearch-category" content="features/api" />
      "custom_fields": {
        "location": "London",
        "genre": ["Rock", "Pop"]
      }
      "highlight": "AddSearch’s <em>REST API</em> 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

Fields in the returned JSON:

  • page: Page number passed as a query parameter
  • total_hits: Total number of documents matching the search term
  • processing_time_ms: Time it took to process the query and return search results (in milliseconds)

Elements in the hits array:

FieldDescriptionTypeNotes
idDocument's IDstring
urlDocument's URLstring
titleDocument's titlestring
meta_descriptionDocument's meta descriptionstringNull if missing.
meta_categoriesDocument's meta categoriesstring, array of meta categoriesNull if missing.
custom_fieldsDocument's custom fieldsstring, object containing custom fieldsEach value is either a string or a string array (if multiple values are defined).
highlightPassage of the document's contentstring
tsDocument's publishing datestringIf the date is not specified, the time when the document was initially indexed is used.
categoriesAutomatically collected domain, URL path, or filetypestring, array of categoriesCategories can be used as search filters.
document_typeHit type: html, pdf, doc, docx, ppt, pptxstring
imagesTop level of the images objectstring, object containing image string and URLs
images.mainURL of the thumbnail (e.g. og:image)stringNull if missing.
images.main_b64Low-resolution version of the thumbnail as a base64 encoded stringstringNull if missing.
images.captureURL of the screen capturestringNull if missing.
scoreHow well the document matches the search termdouble
facetsThe categories with the count of records where search results belong tostring, object containing a custom field or an array of custom fieldsNull if missing.
rangeFacetsThe minimum and maximum value numerical value of the specified rangeNull if missing.

Please note that the Search API endpoint does not require authentication.

Query Limits

The term parameter value has the following limits that cover most of the search queries:

  • Maximum length: 150 characters
  • Maximum number of words: 10 words

Was this helpful?

Need more help?
We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team.