Similarity Service

The PoolParty Similarity Service provides an API to query the engine for similar documents given a document ID and receive response in different formats.

Similarity Request

Request Parameters



id *

The unique identifier of the document to retrieve similar documents for.

fields *

A list of fields used for calculating the document similarity.


The locale of the client, so labels can be resolved to the correct language.

If not set, the service will try to retrieve the locale from the Accept-Language header of the HTTP request.


The index (offset) of the search results returned. (Default: 0)


The number of results that should be returned starting at parameter start. Default: 10


We recommend to use json format as response.

Other acceptable values are:

  • xml

  • rss


Name of a JSP view that is available in the views folder of the search application.

This allows to format the result in any way you want.

Overrides the format of standard serialization!


A list of field names that are defined in the fieldConfig. By setting this parameters you receive content of fields that are not defined in the docFieldConfig.

* mandatory parameters


When performing a search query via HTTP GET, the parameters have to be included in the URL and must be URL-encoded!


Since there can be multiple fields in a similarity search request, they have to be marked as an array by appending square brackets and the array index!

A simple search request could look this this:

  • http://<host>:<port>/search/api/similar?count=10&id=100&fields[0]=title&fields[1]=description&format=json

Which would result in a query with count=10, document id=100 and the fields title and description for similarity calculation. The result will be rendered in the JSON format.


Another way of performing a search query is via HTTP POST. Using POST the request has to be serialized in JSON format and included in the POST body of the request.

Also, the Content-Type header of the request has to be set to application/json so that the server can process the request correctly.


XML is currently not supported as request format, but will follow in a future version.

Similarity Response

Response Elements




The entire similarity request responsible for this response is echoed for convenience.


A list of documents that have been found.

Each document has the standard fields:

  • id - Unique identifier of the document within the index

  • title - The document title

  • link - A link to the document, if available

  • description - A short description of the document

    The default fields are mapped in the document field configuration of the PP Search - Search Server Configuration (AK).

    Also, custom fields can be configured there. If custom fields are defined, they too will be included in the documents of the result.


  • true - If the request has been processed successfully

  • false - If an error occurred while processing. See the message element for further information on the error.


If success is false details on the error may be included in the message.

If the request was successful, usually the query time is included in the message.


The total number of documents found in the index.

Note, this is different from the number of documents actually returned in the results element.

Response Formats


   "results": [
         "title":"A Similar Document",
         "description":"A Similar Document",
         "customAttributes": {