Search Tasks

The search context and search task APIs are designed for a viewer to perform server-side searching and text retrieval of a document.

A search task represents an asynchronous full-text search of a document (via a search context) and yields results as they become available.

Available URLs

POST /v2/searchTasks

Starts an asynchronous full-text search against a search context.

After a successful POST to create the search task, we immediately begin a background process to start populating search results for you to GET. You do not need to wait for the full set of results to be available; you can start retrieving partial search results as soon as they are available. Once the full text of the document has been searched and no more results will be added, the search task state will change from "processing" to "complete".

Request

Request Headers

Request Body

• input
  • contextId (String) Required. Identifies the search context which holds the full-text data to search.
  • searchTerms[] (Array of Objects) Required and must contain at least one item. Each item must be an object which conforms to one of the following:
    • Simple (finds all occurrences of a single regex pattern):
      • type: "simple" (String) Required. Must be set to "simple" to indicate this is a simple term object.
      • pattern (String) Required. Regular expression to search for, using a JavaScript-flavored regular expression string.
      • caseSensitive (Boolean) Determines whether we consider case when matching this term. Default is false.
      • contextPadding (Integer) Maximum number of characters to include both before and after the search result in the returned context string. For example, a value of 25 would allow up to 25 preceding and 25 following characters of content. Default is 25.
      • termId (String) Optional id of your choosing which, if provided, will be included as a termId property on each search result produced by this term. When used, we do not enforce uniqueness; it is your responsibility to use a unique termId for each term.
    • Proximity (finds all occurrences of multiple regex patterns which are near each other):
      • type: "proximity" (String) Required. Must be set to "proximity" to indicate this is a proximity term object.
      • subTerms[] (Array of Objects) Required and must contain at least two items. Each item may contain:
        • pattern (String) Required. Regular expression for this particular term, using a JavaScript-flavored regular expression string.
        • caseSensitive (Boolean) Determines whether we consider case when matching this term. Default is false.
      • distance (Integer) Required. Maximum number of words allowed between any two consecutive search terms.
      • contextPadding (Integer) Maximum number of characters to include both before and after the search result in the returned context string. For example, a value of 25 would allow up to 25 preceding and 25 following characters of content. Default is 25.
      • termId (String) Optional id of your choosing which, if provided, will be included as a termId property on each search result produced by this term. When used, we do not enforce uniqueness; it is your responsibility to use a unique termId for each term.
• minSecondsAvailable (Integer) The minimum number of seconds this search task will remain available. The actual lifetime may be longer.

Successful Response

Response Body

JSON with metadata about the created search task.

• input (Object) Input we accepted to create the search task.
• processId (String) Unique id for this search task.
• affinityToken (String) Affinity token for this search task. Present when clustering is enabled.
• state (String) State of getting search results.
  • "processing" - The search is still being executed. Additional results may become available.
  • "complete" - The search is complete. No additional results will become available.
  • "error" - There was a problem performing the search. No additional results will become available.
• percentComplete (Integer) Percentage of the document text which has been searched (from 0 to 100).
• expirationDateTime (String) Currently planned date and time when the search task resource will expire and no longer be available for use. Format is RFC 3339 Internet Date/Time profile of ISO 8601, e.g. "2016-11-05T08:15:30.494Z".

Error Responses

Example

Request

POST /v2/searchTasks
Content-Type: application/json
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

{
  "input": {
    "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
    "searchTerms": [{
      "type": "simple",
      "pattern": "quick"
    }]
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "input": {
    "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
    "searchTerms": [{
      "type": "simple",
      "pattern": "quick",
      "caseSensitive": false,
      "contextPadding": 25
    }]
  },
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "processing",
  "percentComplete": 0,
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Additional Examples

For more examples of how to construct different searches, see Example Searches.

POST /v2/viewingSessions/{viewingSessionId}/searchTasks

Starts an asynchronous full-text search against a viewing session's source document.

After a successful POST to create the search task, we immediately begin a background process to start populating search results for you to GET. You do not need to wait for the full set of results to be available; you can start retrieving partial search results as soon as they are available. Once the full text of the document has been searched and no more results will be added, the search task state will change from "processing" to "complete".

Request

Request Headers

Request Body

• input
  • searchTerms[] (Array of Objects) Required and must contain at least one item. Each item must be an object which conforms to one of the following:
    • Simple (finds all occurrences of a single regex pattern):
      • type: "simple" (String) Required. Must be set to "simple" to indicate this is a simple term object.
      • pattern (String) Required. Regular expression to search for, using a JavaScript-flavored regular expression string.
      • caseSensitive (Boolean) Determines whether we consider case when matching this term. Default is false.
      • contextPadding (Integer) Maximum number of characters to include both before and after the search result in the returned context string. For example, a value of 25 would allow up to 25 preceding and 25 following characters of content. Default is 25.
      • termId (String) Optional id of your choosing which, if provided, will be included as a termId property on each search result produced by this term. When used, we do not enforce uniqueness; it is your responsibility to use a unique termId for each term.
    • Proximity (finds all occurrences of multiple regex patterns which are near each other):
      • type: "proximity" (String) Required. Must be set to "proximity" to indicate this is a proximity term object.
      • subTerms[] (Array of Objects) Required and must contain at least two items. Each item may contain:
        • pattern (String) Required. Regular expression for this particular term, using a JavaScript-flavored regular expression string.
        • caseSensitive (Boolean) Determines whether we consider case when matching this term. Default is false.
      • distance (Integer) Required. Maximum number of words allowed between any two consecutive sub-terms.
      • contextPadding (Integer) Maximum number of characters to include both before and after the search result in the returned context string. For example, a value of 25 would allow up to 25 preceding and 25 following characters of content. Default is 25.
      • termId (String) Optional id of your choosing which, if provided, will be included as a termId property on each search result produced by this term. When used, we do not enforce uniqueness; it is your responsibility to use a unique termId for each term.
• minSecondsAvailable (Integer) The minimum number of seconds this search task will remain available. The actual lifetime may be longer.

Successful Response

Response Body

JSON with metadata about the created search task.

• input (Object) Input we used to create the search task. May include default values not explicitly provided in the original POST.
• processId (String) Unique id for this search task.
• affinityToken (String) Affinity token for this search task. Present when clustering is enabled.
• state (String) State of getting search results.
  • "processing" - The search is still being executed. Additional results may become available.
  • "complete" - The search is complete. No additional results will become available.
  • "error" - There was a problem performing the search. No additional results will become available.
• percentComplete (Integer) Percentage of the document text which has been searched (from 0 to 100).
• expirationDateTime (String) Currently planned date and time when the search task resource will expire and no longer be available for use. Format is RFC 3339 Internet Date/Time profile of ISO 8601, e.g. "2016-11-05T08:15:30.494Z".

Error Responses

Example

Request

POST /v2/viewingSessions/DLbVh9sTmXJAmd1GeXbS9Gn3WHxs8oib2xPsW2xEFjnIDdoJcudPtxciodSYFQq6zYGabQ_rJIecdbkImTTkSA/searchTasks
Content-Type: application/json

{
  "input": {
    "searchTerms": [{
      "type": "simple",
      "pattern": "quick"
    }]
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "input": {
    "searchTerms": [{
      "type": "simple",
      "pattern": "quick",
      "caseSensitive": false,
      "contextPadding": 25
    }]
  },
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "processing",
  "percentComplete": 0,
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Additional Examples

For more examples of how to construct different searches, see Example Searches.

GET /v2/searchTasks/{processId}

Gets information about a search task.

To get search results, use GET /v2/searchTasks/{processId}/results.

Request

URL Parameters

Request Headers

Successful Response

Response Body

JSON with metadata about the search task.

• input (Object) Input we used to create the search task. May include default values not explicitly provided in the original POST.
• processId (String) Unique id for this search task.
• affinityToken (String) Affinity token for this search task. Present when clustering is enabled.
• state (String) State of getting search results.
  • "processing" - The search is still being executed. Additional results may become available.
  • "complete" - The search is complete. No additional results will become available.
  • "error" - There was a problem performing the search. No additional results will become available.
• percentComplete (Integer) Percentage of the document text which has been searched (from 0 to 100).
• expirationDateTime (String) Currently planned date and time when the search task resource will expire and no longer be available for use. Format is RFC 3339 Internet Date/Time profile of ISO 8601, e.g. "2016-11-05T08:15:30.494Z".

Error Responses

Example

Request

GET /v2/searchTasks/pR5X6nPDgMwat6cxlmn0Q3
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "input": {
    "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
    "searchTerms": [{
      "type": "simple",
      "pattern": "quick",
      "caseSensitive": false,
      "contextPadding": 25
    }]
  },
  "processId": "pR5X6nPDgMwat6cxlmn0Q3",
  "state": "complete",
  "percentComplete": 100,
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

GET /v2/searchTasks/{processId}/results?limit={limit}&continueToken={continueToken}

Gets a block of newly-available search results up to a limit.

This URL is designed to give you the results in chunks as they become available. Each GET request will return the currently-known results up to a limit (default is 100). If a response contains a continueToken, it indicates that additional results may be available and that you should issue another GET request using that continueToken as a query string parameter to skip the results you have already received. As long as a response contains a continueToken, use it to issue a subsequent GET for more results. When you encounter a response which does not have a continueToken, you have received all of the results and no more GET requests are necessary.

In order to optimize the number of network requests you make, any response which contains a continueToken will also contain a continueAfter value with a recommended number of milliseconds you should wait before sending the next GET request.

Request

URL Parameters

Request Headers

Successful Response

Response Body

JSON with any available search results.

• results (Array of Objects) Always present. Array of newly-available search results. If no new results are available, this array will be empty.
  • id (Integer) Unique number assigned to this search result.
  • pageIndex (Integer) Zero-indexed page number where this search result occurs in the document.
  • text (String) Text which was matched.
  • context (String) Contextual excerpt, including the matched text itself. The amount of leading and trailing characters to include in this value is controlled by input.contextPadding in the initial POST to create the search task.
  • boundingRectangle (Object) Bounding rectangle dimensions of the matched text on the page where it occurs.
    • x (Number) Distance from the left edge of the page to the left edge of the search result bounding box.
    • y (Number) Distance from the top edge of the page to the top edge of the search result bounding box.
    • width (Number) Width of the search result bounding box.
    • height (Number) Height of the search result bounding box.
  • lineRectangles (Array of Objects) Array of rectangles for each line of the matched text on the page where it occurs. If the match is on one line, the result is a single array item with a rectangle equal to boundingRectangle. If the match is on multiple lines, all rectangles in the array will be within the bounds of the boundingRectangle.
    • x (Number) Distance from the left edge of the page to the left edge of the search result line rectangle.
    • y (Number) Distance from the top edge of the page to the top edge of the search result line rectangle.
    • width (Number) Width of the search result line rectangle.
    • height (Number) Height of the search result line rectangle.
  • pageData (Object) Information about the dimensions of the page where this search result occurs.
    • width (Number) Width of the page.
    • height (Number) Height of the page.
  • searchTerm (Object) Search term which produced this result. The value will correspond to one of the items passed in to input.searchTerms in the initial POST to create the search task.
    • When type is "simple":
      • type (String) Always present with a value of "simple".
      • pattern (String) Always present. Regular expression which produced this result.
      • caseSensitive (Boolean) Always present. Indicates whether or not case was considered for this result.
      • contextPadding (Integer) Always present. Amount of context padding requested for this term in the initial POST.
      • termId (String) When provided in the initial POST, termId of the term which produced this result.
    • When type is "proximity":
      • type (String) Always present with a value of "proximity".
      • subTerms[] (Array of Objects) Always present. The sub-terms which contributed to this result. Each item will contain:
        • pattern (String) Always present. Regular expression for this particular sub-term.
        • caseSensitive (Boolean) Always present. Indicates whether or not case was considered when matching this particular sub-term in the result.
      • distance (Integer) Always present. Maximum number of words allowed between any two consecutive sub-terms.
      • contextPadding (Integer) Always present. Amount of context padding requested for this term in the initial POST.
      • termId (String) When provided in the initial POST, termId of the term which produced this result.
  • startIndex (Integer) JavaScript string index into the full-page text string where the matched text begins (to get the full-page text string, see GET /v2/searchContexts/{contextId}/records).
  • startIndexInContext (Integer) JavaScript string index into the returned context string where the matched text begins.
• pagesWithoutText (Array of Integers) Always present. Currently known pages in the document which do not contain any text content at all. Values are zero-indexed page numbers. If the search task is still processing (a continueToken is present in the response), the data should be considered partial. Note that, unlike results, this value is cumulative (we always deliver the entire set of pages we know to not contain text data).
• continueToken (String) When present, indicates that more search results may be available. An additional GET request should be made for more results using this value as the continueToken query string parameter. When not present, indicates that the search is complete and no further results will be available.
• continueAfter (Number) Recommended milliseconds to delay before issuing the next GET request for more results.

Error Responses

Example

Say you have a search task which was created to find the regex "manag[a-z]*" in a particular whitepaper. Here is an example sequence of requests and responses illustrating how you would acquire the full set of results for the search task (for brevity, the total number of search results in this example is small).

You would start with an initial GET:

GET /v2/searchTasks/pR5X6nPDgMwat6cxlmn0Q3/results
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "id": 0,
      "pageIndex": 0,
      "text": "Management",
      "context": "Enterprise Content Management Best Practices",
      "boundingRectangle": { "x": 24.20, "y": 13.74, "width": 234.20, "height": 26.10 },
      "lineRectangles": [{ "x": 24.20, "y": 13.74, "width": 234.20, "height": 26.10 }],
      "pageData": { "width": 612, "height": 792 },
      "searchTerm": {
        "type": "simple",
        "pattern": "manag[a-z]*",
        "caseSensitive": false,
        "contextPadding": 25
      },
      "startIndex": 19,
      "startIndexInContext": 19
    },
    {
      "id": 1,
      "pageIndex": 0,
      "text": "management",
      "context": "ue of enterprise content management software should go way b",
      "boundingRectangle": { "x": 156.07, "y": 352.19, "width": 105.00, "height": 13.41 },
      "lineRectangles": [{ "x": 156.07, "y": 352.19, "width": 105.00, "height": 13.41 }],
      "pageData": { "width": 612, "height": 792 },
      "searchTerm": {
        "type": "simple",
        "pattern": "manag[a-z]*",
        "caseSensitive": false,
        "contextPadding": 25
      },
      "startIndex": 527,
      "startIndexInContext": 25
    }
  ],
  "pagesWithoutText": [],
  "continueToken": "Cx07GHlkmi32gxAQhv49WZ",
  "continueAfter": 500
}

The initial response has given us two results for the first page of the document (page index 0) and a continueToken which we should use to get more results after waiting 500 milliseconds.

So, half a second later, we issue a follow-up request with the continueToken passed in as a query string parameter (so we skip over the results we already have):

GET /v2/searchTasks/pR5X6nPDgMwat6cxlmn0Q3/results?continueToken=Cx07GHlkmi32gxAQhv49WZ
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "id": 2,
      "pageIndex": 1,
      "text": "management",
      "context": "Enterprise content management software helps eliminate",
      "boundingRectangle": { "x": 310.21, "y": 562.14, "width": 254.03, "height": 26.10 },
      "lineRectangles": [{ "x": 310.21, "y": 562.14, "width": 254.03, "height": 26.10 }],
      "pageData": { "width": 612, "height": 792 },
      "searchTerm": {
        "type": "simple",
        "pattern": "manag[a-z]*",
        "caseSensitive": false,
        "contextPadding": 25
      },
      "startIndex": 652,
      "startIndexInContext": 19
    }
  ],
  "pagesWithoutText": [2,3],
  "continueToken": "B4uGe7m0ZtxR3lkqA07Nmj",
  "continueAfter": 500
}

This time we get back a new result as well as some new information about pagesWithoutText: we now know that at least page indices 2 and 3 (zero-indexed page numbers) have no text at all.

The presence of a new continueToken tells us there may be more results, so we submit another request with the new continueToken:

GET /v2/searchTasks/pR5X6nPDgMwat6cxlmn0Q3/results?continueToken=B4uGe7m0ZtxR3lkqA07Nmj
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "id": 3,
      "pageIndex": 5,
      "text": "management",
      "context": "upply chains to contract management, or HR processes to gove",
      "boundingRectangle": { "x": 67.00, "y": 142.53, "width": 254.03, "height": 26.10 },
      "lineRectangles": [{ "x": 67.00, "y": 142.53, "width": 254.03, "height": 26.10 }],
      "pageData": { "width": 612, "height": 792 },
      "searchTerm": {
        "type": "simple",
        "pattern": "manag[a-z]*",
        "caseSensitive": false,
        "contextPadding": 25
      },
      "startIndex": 113,
      "startIndexInContext": 25
    }
  ],
  "pagesWithoutText": [2,3,4]
}

This time we get a new result for page index 5, and we now know that page indices 2, 3, and 4 all contain no text at all (apparently this was not much of a whitepaper!). The lack of a continueToken tells us we have received all of the results, so there are no more GET requests to make.

DELETE /v2/searchTasks/processId

Cancels the search task. Further requests using this processId will return errors.

Request

URL Parameters

Request Headers

Successful Response

HTTP/1.1 204 No Content

Error Responses

Example Searches

The following examples demonstrate how to use input.searchTerms for both the POST /v2/searchTasks and POST /v2/viewingSessions/{viewingSessionId}/searchTasks URLs.

Start a search for a single word

This partial input JSON begins a search task which finds all instances of the word "quick":

{
  "input": {
    "searchTerms": [{
      "type": "simple",
      "pattern": "quick"
    }]
  }
}

Start a case-sensitive search for an exact phrase

This partial input JSON begins a case-sensitive search for the exact phrase "The quick brown fox jumped over the lazy dog.". Notice that we had to escape the period character because it is a special regex character (\.), and because this is a JSON string value, the backslash itself must also be escaped ("\\."):

{
  "input": {
    "searchTerms": [{
      "type": "simple",
      "pattern": "The quick brown fox jumped over the lazy dog\\.",
      "caseSensitive": true
    }]
  }
}

Start a search for every instance of the word "quick" or "brown" or "fox"

This partial input JSON begins a search for the words "quick" or "brown" or "fox", locating all instances of each of these words:

{
  "input": {
    "searchTerms": [{
      "type": "simple",
      "pattern": "quick"
    }, {
      "type": "simple",
      "pattern": "fox"
    }, {
      "type": "simple",
      "pattern": "dog"
    }]
  }
}

Start a search for "quick" and "fox" and "dog" where there are no more than 5 words between any two consecutive occurrences of them

{
  "input": {
    "searchTerms": [{
      "type": "proximity",
      "subTerms": [{
        "pattern": "quick"
      }, {
        "pattern": "fox"
      }, {
        "pattern": "dog"
      }],
      "distance": 5
    }]
  }
}

Start a case-sensitive search for "John Doe" within 30 words of what looks like a social security number

{
  "input": {
    "searchTerms": [{
      "type": "proximity",
      "subTerms": [{
        "pattern": "John Doe",
        "caseSensitive": true
      }, {
        "pattern": "\\d{3}-\\d{2}-\\d{4}"
      }],
      "distance": 30
    }]
  }
}