API Reference

GET /v1/search/{index public key}

Retrieve search results from the index.

Required Query Parameter

  • term: Search term (also known as the keyword)

Optional Query Parameters

  • limit: Number of results to return per page (default: 10. Must be 1-300)
  • page: Page to return (default: 1)
  • jsonp: JavaScript function call wrapped around the response JSON
  • lang: Return results only with this language (e.g. “en” or “de”)
  • categories: Limit search to certain categories (domain or URL path). E.g. “0xdomain.com” would return results only from domain.com, 1xnews would return results from “domain.com/news/*” path
  • sort: relevance (default) or date
  • order: desc (default) or asc. Only applicable if “sort=date”
  • fuzzy: false (default), true, or “auto”. Also match words that are close to the defined keywords. Off by default. The suggested value is “auto”.
  • postfixWildcard: true (default), false. Adds a wildcard at the end of the term. Ideal for search-as-you-type feature. Set it to false if you want to emphasise exact matches (you will get less results and better highlights).
  • dateFrom: return only results that are newer than the given date, in yyyy-MM-dd format (example: 2018-12-15)
  • dateTo: return only results older than given date, in yyyy-MM-dd format
  • customField: return only results containing the given custom field and value pair, in “key=value” URL encoded format (so key%3Dvalue). Multiple custom field pairs can be defined by adding additional customField parameters to the query. 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. Example: &customField=city%3Dlondon&customField=genre%3Drock&customField=genre%3Dpop (city=London AND (genre=rock OR genre=pop))
  • resultType: all (default) or organic (results without Pinned results or Promotions)
  • userToken: user token for search personalization
  • facet: return categories where search results belong to. Pass one or more custom fields to receive facets of said fields. For example, facet=genre&facet=artist would return search result aggregations by genre and artist custom fields.
  • numFacets: limit the maximum number of aggregations returned for each field defined with facet parameter. The default is 10, the maximum value is 100.
  • rangeFacets: allows to group numerical custom fields into ranges. Example:
    [
        {
          "field: "custom_fields.price",
          "ranges": [
              { "to": 10 },
              { "from": 10, "to": 20 },
              { "from": 20 }
            ]
        }
    ]
    

    The paramater 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

  • collectAnalytics: true (default) or false. Defines if the search event is added to the statistics shown in the Dashboard.
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:

  • id: Document’s ID (md5 of the URL)
  • url: Document’s URL
  • title: Documents’s title
  • meta_description: Documents’s meta description
  • highlight: Part of the document’s content
  • ts: Document’s publishing date. if unknown, the time when the document was initially indexed
  • categories: Categories where the page belongs. These can be used to filter down the search query to a specific domain or path part
  • document_type: Hit type: html, pdf, doc, docx, ppt, pptx
  • images.main: URL of the main image (e.g. og:image). Null if missing
  • images.main_b64: Low resolution version of the main image as a base64 encoded string
  • images.capture: URL of the screen capture. Null if missing
  • score: How well the search term matches the document
  • custom_fields: custom fields defined for the document. Each value is either a string or a string array (if multiple values defined).
  • facets: categories with the count of records where search results belong to.

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