Search

The Search endpoint is used to Perform Search Requests and view results in the Document Hit Viewer.

Accepts content-type application/json only
Serves content-type application/json only
Accepts POST requests only

Authentication

A Valid APIKey with Read Permission to all specified indexes must be passed with every request.

Performing a Search Request

Arguments

Indexes - An array of Indexes to search containing:-
- IndexID - The ID of the Index
- IndexUUID - The UUID of the Index
Parameters - All Search Parameters
- Query - A query string
- ResultsPerPage (Optional, Default 10) - Any number between 1 and 1024
- MaxResults (Optional, Default 500) - The maximum amount of results to retrieve - Any number between 1 and 1000
- Page (Optional, Default 1) - The page to retrieve in the result-set.
- IncludeContext (Optional, Default false) - Whether or not to include Words of Context in the Search Result. Pass true to retrieve words of context.
- AutoStop (Optional, Default 100,000,000) - Automatically stops searching after a certain amount of documents have been found. Provides a way to limit time spent when a broad search retrieves a very large number of documents.
- Stemming (Optional, Default false) - Set to true to search with Stemming Enabled.
- Synonyms (Optional, Default false) - Set to true for Synonym Searching.
- Sort (Optional) - Sort Search Results
- GetTopFieldValues (Optional) - Request Statistics about Field Value occurrences. Used for Facet Searching
- Filters (Optional) - Any Filters. See Facet Searching

The below shows the bare-minimum information required to perform a Search Request:

Examples

Example Request

{
  "APIKey": "########-####-####-#################",
  "Indexes": [
    {
      "IndexID": 456,
      "IndexUUID": "########-####-####-#################"
    },
    {
      "IndexID": 702,
      "IndexUUID": "########-####-####-#################"
    }
  ],
  "Parameters": {
    "Query": "ipsum",
    "Page": 1,
    "IncludeContext": true
  }
}

Example Response

{
  "DocCount" : 2,
  "Errors": [],
  "Hits": 3,
  "Results": [
    {
      "FileUUID": "########-####-####-#################",
      "Size": 34562353,
      "DocHitCount": 1,
      "DocHitsPos": [2],
      "TypeID": 1,
      "DateUploaded": "2018-06-06T16:56:30.883Z",
      "DocDisplayName": "Lorem Ipsum",
      "Context": "...Lorem <b>ipsum</b> dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor...",
      "ResultIndex": 0
    },
    {
      "FileUUID": "########-####-####-#################",
      "Size": 34562353,
      "DocHitCount": 2,
      "DocHitsPos": [32,64],
      "TypeID": 4,
      "DateUploaded": "2018-06-06T16:56:30.885Z",
      "DocDisplayName": "Various Vehicles by Toyota",
      "Context": "...The first generation, named <b>Ipsum</b> in Japan and Picnic in export markets, was built from 1995–2001, with export versions arriving in 1996...",
      "ResultIndex" : 1
    }
  ]
}

DocCount: The number of documents found by this search.
Note that, results are paginated by ResultsPerPage.
Errors: A list of Error Codes, if any occur.
Hits: How many hits were found in the documents.
Results: An array of documents, paginated based on the Page passed.
- FileUUID: The FileUUID used for manipulating this file. See /Files
- Size: The size of the file, in bytes.
- DocHitCount: How many hits were found in the file for the search query.
- DocHitsPos: The index of words at which a hit occurs.
- TypeID: The ID of the detected File Type.
- DateUploaded: The date the file was uploaded.
- DocDisplayName: The display name of the document, or a field value if UseFieldsAsDisplayName was passed.
- Context: The words of Context surrounding the first hit in the document. Only present if IncludeContext was passed.
- ResultIndex: The Index of the Result.

Document Hit Viewer

The Document Hit Viewer is used to retrieve and convert to HTML any documents found in a Search Request. It is used for retrieving and displaying individual results.

The Document Hit Viewer can serve many common file formats as HTML, including

Requesting the Hit Viewer

Requests for the Hit Viewer are performed via the same endpoint as search requests, /search

Arguments

The Hit Viewer requires the same arguments used to make the original search request. In addition, the following Parameters must be passed:-

Version Should pass 3 for present Hit Viewer Syntax.
HitViewer Including the following arguments:
- DocIndex The ResultIndex of the document in the Search Results to retrieve.
- ExtractImages (optional, default: true) whether the Hit Viewer will include images embedded in the original document. Note that image retrieval counts towards Data Retrieval in billing.
- BaseHref (optional) Sets the base Href value in the document. Useful for preserving relative links.

Example Request

{
  "APIKey": "########-####-####-#################",
  "Indexes": [
    {
      "IndexID": 456,
      "IndexUUID": "########-####-####-#################"
    },
    {
      "IndexID": 702,
      "IndexUUID": "########-####-####-#################"
    }
  ],
  "Parameters": {
    "Query": "ipsum",
    "Page": 1,
    "Version" : 3,
    "HitViewer" : 
    {
      "DocIndex": 2,
      "ExtractImages": true,
      "BaseHref": "www.example.com"
    }
  }
}

Example Response

{
  "Errors" : [],
  "HitViewer" : 
  {
    "Errors" : [],
    "Html" : "..."
  }
}

Errors A list of Error Codes, if any occur during the Search Request.
HitViewer
- Errors Any error codes occurring from extracting the document.
- Html The entire document, converted to HTML with additional span elements for highlighting and navigating hits.

Highlighting and Navigating Hits

Hits within the document are surrounded with <span> elements:

<span id="hit_2" class="dts_hit" data-next="hit_3" data-prev="hit_0">ipsum</span>

Highlighting Hits

Add a CSS rule to the document for the class dts_hit

Example

.dts_hit {
  background-color: yellow;
}

Navigating Hits

Use JavaScript to scroll to the id of elements classed dts_hit inside the document.

The id of hits follows the pattern hit_1, hit_2 … with the exception of the last hit, which is always hit__last

Use the data-next and data-prev attributes to identify the id of the next and previous hit.

Example

The following example assumes you have added two buttons, btnNextHit and btnPrevHit.

It requires jQuery and AnimatedScroll.js

  let current_hit = $('#hit_1');
  let btnNextHit = $('#btnNextHit');
  let btnPrevHit = $('#btnPrevHit');
  
  btnNextHit.click(function() {
      let next_hit = $('#' + current_hit.attr('data-next'));
      goToHit(next_hit);
  });
  
  btnPrevHit.click(function() {
      let prev_hit = $('#' + current_hit.attr('data-prev'));
      goToHit(prev_hit);
  });
  
  // Scroll to the given hit
  function goToHit(hit) {
      // Update the current hit
      current_hit = hit;
      // Scroll the hit into view
      current_hit.animatedScroll(
          {
              duration: 'normal',
              easing: 'easeOutExpo'
          }
      );
      // Suggestion: Add other logic such as
      // * Disable the previous button at the first hit
      // * Disable the next button at the last hit
      // * Highlighting the active hit a different colour.
  }