Search Contexts

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 context contains a collection of records of full-page text data, one record per page.

Available URLs

POST /v2/searchContexts

Creates a search context which will eventually hold a set of full-page text records for a source document.

After a successful POST to create the search context, we immediately begin a background process to extract the text records using a work file you specified in the POST (via input.fileId). As we extract pages of text, new records will become available for you to GET. The search context state will change from "processing" to "complete" when there are no more records to extract.

Request

Request Headers

Request Body

• input
  • documentIdentifier (String) Required. Your own unique identifier for the source document. It is crucial that you use a unique value for each unique document, otherwise, the returned text for a document will not be correct.
  • source (String) Required. The following values are allowed:
    • "workFile" - indicates that the server should use an existing work file and extract the text from it.
    • "upload"- indicates that the user would like to upload previously extracted text to the server to be used for search.
  • fileId (String) Required with source: "workfile". The id of the work file to extract text records from.
  • password (String) Password to open the source document, when using a source of "workFile".
• minSecondsAvailable (Integer) The minimum number of seconds this search context will remain available. The actual lifetime may be longer.

Successful Response

Response Body

JSON with metadata about the created search context. You can check for changes to this metadata with additional GET requests.

• input (Object) Input we accepted to create the search context.
• contextId (String) Unique id for this search context.
• affinityToken (String) Affinity token for this search context. Present when clustering is enabled.
• state (String) State of acquiring text records for the given input.documentIdentifier.
  • "processing" - The server is acquiring text records. No further actions are needed.
  • "awaitingInput" - The server is waiting for text to be uploaded by client. The client should take action and provide all required text records. This state only occurs when the client created a searchContext using input.source: "upload". Note that based on the provided documentIdentifier, the server may skip this state and go directly to "processing" or "complete" if it determines that it already has the required data.
  • "complete" - All text records have been acquired.
  • "error" - There was a problem acquiring text records.
• percentComplete (Integer) Percentage of text records which have been acquired (from 0 to 100).
• expirationDateTime (String) Currently planned date and time when the search context resource will expire and no longer be available for use. This time may be extended if we have need to keep using the data (for example, if there are search tasks executing against this context). Format is RFC 3339 Internet Date/Time profile of ISO 8601, e.g. "2016-11-05T08:15:30.494Z".
• errorCode (String) Descriptive error code. Present when state is "error".
• errorDetails (Object) Additional error details, if any. May be present when errorCode is present.

Error Responses

Examples

Creating a searchContext using a workfile:

Request

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  }
}

Response

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "state": "processing",
  "percentComplete": 0,
  "expirationDateTime": "2016-12-17T20:38:39.796Z",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Creating a searchContext using previously extracted text:

Note that it is recommended that you use the Accusoft-Affinity-Hint header here when working in multi-server mode, so that multiple contexts created for the same document can be routed to the same server when possible.

Request

POST /v2/searchContexts
Content-Type: application/json
Accusoft-Affinity-Hint: "your-own-unique-identifier-for-the-source-document"

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "upload"
  },
  "minSecondsAvailable": 1200
}

Response

200 OK
Content-Type: application/json

{

  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "upload"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "state": "awaitingInput",
  "percentComplete": 0,
  "expirationDateTime": "2016-12-17T20:38:39.796Z",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

GET /v2/searchContexts/{contextId}

Gets information about a search context.

Request

URL Parameters

Request Headers

Successful Response

Response Body

JSON with current metadata about the search context.

• input (Object) Input we accepted to create the search context.
• contextId (String) Unique id for this search context.
• affinityToken (String) Affinity token for this search context. Present when clustering is enabled.
• state (String) State of acquiring text records for the given input.documentIdentifier.
  • "processing" - The server is acquiring text records. No further actions are needed.
  • "awaitingInput" - The server is waiting for text to be uploaded by client. The client should take action and provide all required text records. This state only occurs when the client created a searchContext using input.source: "upload". Note that based on the provided documentIdentifier, the server may skip this state and go directly to "processing" or "complete" if it determines that it already has the required data.
  • "complete" - All text records have been acquired.
  • "error" - There was a problem acquiring text records.
• percentComplete (Integer) Percentage of text records which have been acquired (from 0 to 100).
• expirationDateTime (String) Currently planned date and time when the search context resource will expire and no longer be available for use. This time may be extended if we have need to keep using the data (for example, if there are search tasks executing against this context). Format is RFC 3339 Internet Date/Time profile of ISO 8601, e.g. "2016-11-05T08:15:30-05:00".
• errorCode (String) Descriptive error code. Present when state is "error".
• errorDetails (Object) Additional error details, if any. May be present when errorCode is present.

Error Responses

Examples

Example request

GET /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Response when the state is still "processing"

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "processing",
  "percentComplete": 47,
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Response when the state is "complete"

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "complete",
  "percentComplete": 100,
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Response when the state is "error" because the work file could not be found

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "errorCode": "ResourceNotFound",
  "errorDetails": {
    "in": "searchContext",
    "at": "input.fileId"
  },
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Response when the source document required a password but no password was provided

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "errorCode": "InvalidPassword",
  "errorDetails": {
    "in": "searchContext",
    "at": "input.password"
  },
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

Response when the source document required a password but the wrong password was provided

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

{
  "input": {
    "documentIdentifier": "your-own-unique-identifier-for-the-source-document",
    "source": "workFile",
    "fileId": "ek5Zb123oYHSUEVx1bUrVQ",
    "password": "wrong-password"
  },
  "contextId": "ElkNzWtrUJp4rXI5YnLUgw",
  "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
  "state": "error",
  "errorCode": "InvalidPassword",
  "errorDetails": {
    "in": "searchContext",
    "at": "input.password"
  },
  "expirationDateTime": "2016-12-17T20:38:39.796Z"
}

DELETE /v2/searchContexts/{contextId}

Deletes a search context. Further requests using this contextId will return errors.

Request

URL Parameters

Request Headers

Successful Response

This request returns no body in the response when successful.

Error Responses

Examples

Example request

DELETE /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Response

HTTP/1.1 204 No Content

PUT /v2/searchContexts/{contextId}/records

This URL is used to upload one or more previously extracted text records to a search context.

Note that this is only necessary when creating a searchContext using input.source of "upload" and receive a state of "awaitingInput".

Request

URL Parameters

Request Headers

Request Body

Note: since this is previously extracted text being uploaded, the body of the request corresponds to the body of the response on GET /v2/searchContexts/{contextId}/records.

• pages[] (Array of Objects) Array of full-page text record objects for the requested pages. Note that the order of the records is not guaranteed; you must use the number property of each returned item to know its page index. Items may contain:
  • number (Integer) Required. Page index (zero-indexed page number). The property is named simply number for backwards compatibility reasons.
  • text (String) Page text. Either text or errorCode is required.
  • errorCode (String) A value indicating there was a problem with the page text. Either text or errorCode is required.
  • width (Number) Required with text. Page width.
  • height (Number) Required with text. Page height.
  • rectangles[] (Array of Arrays) Required with text. Bounding boxes for individual glyphs on the page. Each item will contain four numbers:
    • [0] (Number) Distance from the left edge of the page to the left edge of the glyph bounding box.
    • [1] (Number) Distance from the top edge of the page to the top edge of the glyph bounding box.
    • [2] (Number) Width of the glyph bounding box.
    • [3] (Number) Height of the glyph bounding box.
  • markup[] (Array of Objects) Objects describing hyperlinks, if any. Each item may contain:
    • changeType (String) Value will always be "Add".
    • markType (String) Value will always be "DocumentHyperlink".
    • properties (Object) Properties of the hyperlink.
      • href (String) Destination URL.
      • rectangle (Object) Dimensions of the hyperlink bounding box on the page.
        • x (Number) Distance from the left edge of the page to the left edge of the hyperlink bounding box.
        • y (Number) Distance from the top edge of the page to the top edge of the hyperlink bounding box.
        • width (Number) Width of the hyperlink bounding box.
        • height (Number) Height of the hyperlink bounding box.
      • borderThickness (Number) Border thickness which should be applied.
      • borderHorizontalRadius (Number) Horizontal border radius which should be applied.
      • borderVerticalRadius (Number) Vertical border radius which should be applied.
      • borderOpacity (Integer) Border opacity which should be applied. Value will be from 0 to 255, where 0 represents fully transparent and 255 represents fully opaque.

Successful Response

This request returns no body in the response when successful.

Error Responses

Examples

Example request

PUT /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw/records
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=
Content-Type: application/json

{
  "pages": [{
    "number": 1,
    "text": "the text to be searched",
    "width": 147,
    "height": 349
    "rectangles": [
      [ 23.6, 767.75, 15.01, 23.08 ],
      ...
    ]
  }, ...]
}

Example responses

When the data was successfully accepted

HTTP/1.1 200 OK

When the search context is not awaiting input

HTTP/1.1 480 IncorrectUsage
Content-Type: application/json

{
  "errorCode": "IncorrectUsage",
  "errorDetails": {
    "in": "searchContext",
    "at": "state",
    "actual": "processing",
    "expected": {
      "value": "awaitingInput"
    }
  }
}

POST /v2/searchContexts/{contextId}/completed

This URL is used to let the server know that all previously extracted records have been uploaded.

Note that this is only necessary when creating a searchContext using input.source of "upload" and receive a state of "awaitingInput".

The provided records should make up a set of contiguous page records (e.g. [1,2,3,4,5] and not [1,2,3,5,27]), and if any pages are missing from the set, the context will not be allowed to complete successfully.

Request

URL Parameters

Request Headers

Request Body

This request has no body.

Successful Response

This request returns no body in the response when successful.

Error Responses

Examples

Example request

POST /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw/completed
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Example responses

When the context is successfully completed

HTTP/1.1 200 OK

When a non-contiguous range of pages is provided (e.g. [1, 2, 3, 5, 27])

HTTP/1.1 480 MissingRecords
Content-Type: application/json

{
  "errorCode": "MissingRecords"
}

When the state of the context is "error"

HTTP/1.1 480 ResourceNotUsable
Content-Type: application/json

{
  "errorCode": "ResourceNotUsable"
}

When the context is not awaiting input

HTTP/1.1 480 IncorrectUsage
Content-Type: application/json

{
  "errorCode": "IncorrectUsage",
  "errorDetails": {
    "in": "searchContext",
    "at": "state",
    "actual": "processing",
    "expected": {
      "enum": ["awaitingInput","complete"]
    }
  }
}

GET /v2/searchContexts/{contextId}/records?pages={pages}

Gets full-page text data (records) for a specified set of pages.

Request

URL Parameters

pages

The pages parameter accepts one or more zero-indexed page numbers (page indices). Between commas, you can specify individual pages (like 0), closed page ranges (like 0-3), and open-ended page ranges (like 3-, which means page index 3 through the end of the document).

Here are some examples:

Request Headers

Successful Response

JSON containing full-page text records for the requested pages.

• pages[] (Array of Objects) Always present. Array of full-page text record objects for the requested pages. Note that the order of the records is not guaranteed; you must use the number property of each returned item to know its page index. Items may contain:
  • number (Integer) Always present. Page index (zero-indexed page number). The property is named simply number for backwards compatibility reasons.
  • text (String) Page text.
  • errorCode (String) A descriptive page-level error code (such as "CouldNotGetPageData") if there was a problem getting data for the page.
  • width (Number) Page width.
  • height (Number) Page height.
  • rectangles[] (Array of Arrays) Bounding boxes for individual glyphs on the page. Each item will contain four numbers:
    • [0] (Number) Distance from the left edge of the page to the left edge of the glyph bounding box.
    • [1] (Number) Distance from the top edge of the page to the top edge of the glyph bounding box.
    • [2] (Number) Width of the glyph bounding box.
    • [3] (Number) Height of the glyph bounding box.
  • markup[] (Array of Objects) Objects describing hyperlinks, if any. Each item may contain:
    • changeType (String) Value will always be "Add".
    • markType (String) Value will always be "DocumentHyperlink".
    • properties (Object) Properties of the hyperlink.
      • href (String) Destination URL.
      • rectangle (Object) Dimensions of the hyperlink bounding box on the page.
        • x (Number) Distance from the left edge of the page to the left edge of the hyperlink bounding box.
        • y (Number) Distance from the top edge of the page to the top edge of the hyperlink bounding box.
        • width (Number) Width of the hyperlink bounding box.
        • height (Number) Height of the hyperlink bounding box.
      • borderThickness (Number) Border thickness which should be applied.
      • borderHorizontalRadius (Number) Horizontal border radius which should be applied.
      • borderVerticalRadius (Number) Vertical border radius which should be applied.
      • borderOpacity (Integer) Border opacity which should be applied. Value will be from 0 to 255, where 0 represents fully transparent and 255 represents fully opaque.
• errorCode (String) Descriptive error code. Present if there was a general problem getting all of the requested data.
• errorDetails (Object) Present if there are additional error details.

Error Responses

Examples

When all data is returned successfully

Request records for pages 0 through 9:

GET /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw/records?pages=0-9
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

Successful response (where ... indicates that data has been omitted for brevity):

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

{
  "pages": [
    {
      "number": 0,
      "text": "the page text",
      "width": 648.00,
      "height": 828.00,
      "rectangles": [
        [
          202.25,
          135.05,
          27.00,
          73.26
        ],
        [
          229.25,
          135.05,
          30.00,
          73.26
        ],
        ...
      ]
      "markup": [
        {
          "changeType": "Add",
          "markType": "DocumentHyperlink",
          "properties": {
            "rectangle": {
              "height": 14.71,
              "width": 86.20,
              "y": 73.50,
              "x": 71.31
            },
            "borderHorizontalRadius": 0.0,
            "borderVerticalRadius": 0.0,
            "borderThickness": 0.0,
            "href": "http://www.google.com/",
            "borderOpacity": 255
          }
        },
        ...
      ]
    },
    ...
  ]
}

When the data stream is interrupted

Because this URL may return large amounts of data, we progressively stream data to the HTTP response. As such, it is possible that we encounter a data streaming error after we have sent HTTP 200. When this happens, we will close the JSON with a top-level errorCode of "DataStreamInterruption", like so:

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

{
  "pages": [...],
  "errorCode": "DataStreamInterruption"
}

When out-of-range, non-existent pages are requested

If you request a set of pages that include non-existent pages beyond the length of the document, we will include whatever actual pages we can, but we will also add a top-level errorCode of "RequestedPagesOutOfRange" with the actual documentPageCount within an errorDetails object, like so:

GET /v2/searchContexts/ElkNzWtrUJp4rXI5YnLUgw/records?pages=0-9
Content-Type: application/json
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

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

{
  "pages": [...],
  "errorCode": "RequestedPagesOutOfRange",
  "errorDetails": {
    "documentPageCount": 3
  }
}

When data cannot be extracted from some pages

The pages array will contain one item for each requested page that actually exists. If we are unable to obtain data for a particular page, we will include an item in the pages array that contains the page number and a page-specific errorCode of "CouldNotGetPageData", like so:

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

{
  "pages": [
    {
      "number": 0,
      "text": "Once upon a time...",
      "width": 612.00,
      "height": 792.00,
      "rectangles": [...]
    },
    {
      "number": 1,
      "errorCode": "CouldNotGetPageData"
    },
    {
      "number": 2,
      "errorCode": "CouldNotGetPageData"
    },
    {
      "number": 3,
      "text": "and then, she said to the dragon...",
      "width": 612.00,
      "height": 792.00,
      "rectangles": [...]
    }
  ]
}