text/paraphrase

Obtain a list of paraphrases (i.e., alternate wordings) for a search query.

Resource URL

GET/POST http(s)://api.idilia.com/1/text/paraphrase.{format}

Description

Send a request to paraphrase a search query. Can be used in synchronous or batch mode. In synchronous mode, the paraphrases are returned in the reponse. In batch mode, the request returns immediately and the response document is deposited at the URI specified once generated.

In addition to the paraphrases, the sense annotations for the submitted query may also be obtained by specifying parameter wsdMime.

The text to paraphrase can either be provided as parameter text or as a distinct part in a multipart request. HTTP method POST is used when issuing a multipart request. Either GET or POST may be used for single part requests.

Request

The request is an HTTP GET or POST with the following query parameters:

disambiguationRecipe	Recipe identifier for the linguistic processing of the request. Please refer to Sense Analysis Recipes for available values. Not all values may be supported by a specific configuration. Optional. Default: defaultPrecision Example value : highestPrecision
key	When using simple authentication, this parameter contains the concatenation of your access key and private key. See Authentication for more details. Optional. Default: none Example value : Idi123rlzKT90yoUavrzoRbkdHgsoZTiYR2qaYA8SxA
maxCount	Maximum number of paraphrases to generate for the search query. Optional. Default: 10 Example value: 5
minWeight	Minimum weight for returned paraphrases. Value is between 0.0 and 1.0. Optional. Default is 0.0 Example value : 0.50
notificationURI	URI in the form "sqs://queue" in Amazon Simple Queue Service (SQS) where a notification with the result of processing the request is delivered. This notification does not include the annotated document. Queue must be writable from Idilia's account (AWS Account: 933890641136). Optional. Only used in batch mode. Example value : sqs://queue.amazonaws.com/2345433344/idilia-notif
paraphrasingRecipe	Recipe identifier for the paraphrasing processing of the request. Please refer to Paraphrasing Recipes for available values. Not all values may be supported by a specific configuration. Optional. Default: paidListing Example value : paidListing
requestId	Unique identifier supplied by the application to assist correlating the server's responses with the application's requests. Echoed transparently by the server. Optional. Default: none Example value : some-app-req-1234
resultURI	URI for a location where the result document can be deposited when available. It can be a URI in the form "ftp://site/dropbox/file" where an FTP server will accept anonymous uploads. Any valid CURL (http://curl.haxx.se/) URI can be specified. The URI can also be in the form "s3://bucket/file" where this corresponds to an Amazon Web Service S3 bucket with a write policy that allows writes from Idilia's account (AWS Account: 933890641136). The presence of this parameter triggers batch mode. Example value : ftp://somedomain.com/dropbox/documentA.semdoc.xml
text	Text to process. Must agree with the supplied textMime. Alternatively the text to process can be supplied as a separate mime-attached part. Mandatory if no mime-attached part. Example value : popular vacation spots in orlando
textMime	Mime type of the supplied text when not supplying the text as an separate mime-attached part. This should always be "text/query" with the appropriate character set specification. Mandatory when using parameter text. Example value : text/query; charset=utf8
timeout	Timeout in units of hundreds of milliseconds for returning a result (i.e., a value of 10 returns after 1 second). If the scheduling delay + computation time exceeds this limit, the request aborts immediately and returns HTTP 504. Useful for real-time applications. Optional. Default: no timeout Example value : 10
wsdMime	Mime type of the sense annotated result if desired. For a list of the valid mime types, refer to Annotated Document Mime Types. By default this is not specified and only the paraphrases are returned. Optional. Default: none Example value : application/x-semdoc+xml

Note: A multipart request must follow the format of RFC2045 and be of mime multipart/mixed. The first part contains the request parameters in a mime attachment of type application/x-www-form-urlencoded. The second part contains the document to process and must have one of the mime types described in Source Document Mime Types. This part may be encoded with "gzip" (RFC1952). When this is the case, header "Content-Type: gzip" must be set on the document part.

Note: Parameter textMime should always be "text/query" with the appropriate character set. E.g., "text/query; charset=UTF-8".

Response

The format of the response is determined by the extension provided on the request URL. The following are supported:

Extension	Format
.json	A single part document containing a JSON object.
.xml	A single part document containing an XML object.
.mpjson	A multipart document where the first part is a JSON object formatted as described above and the second part is the disambiguated query in the format requested by wsdMime.
.mpxml	A multipart document where the first part is an XML object formatted as described above and the second part is the disambiguated query in the format requested by wsdMime.

Note: Multipart responses: A multipart response follows the format of RFC2045. The first part has mime type application/json or application/xml and the second part has the mime type requested using parameter wsdMime.

The response elements are the following:

errorMsg	This parameter is present when an error was encountered when processing the request (i.e., status != 200). It is a string containing a descriptive cause of the error encountered.
paraphrases	This element contains the list of paraphrases generated. The paraphrases are either expressed as senses or words depending on the specified paraphrasingRecipe.
query	This element contains the sense annotated query and is present only in single part responses. Its format is determined by request parameter wsdMime.
requestId	This parameter echoes the string provided as parameter requestId in the request. It can be used by applications to correlate requests and responses.
status	This parameter is a numeric return code for the request. The value corresponds to the HTTP return codes. For example, "200" indicates that the request was successfully processed. "400" is the code for a bad request.

Paraphrasing Output

The method returns a list of paraphrases sorted in decreasing closeness to the original query. The first paraphrase is always the original query. It has attribute weight of 1. The remaining paraphrases have a weight based on the accuracy of the algorithm that generated the paraphrase (for example, performing a substitution with a synonym).

Request Authentification

All requests must be authenticated as described in Authentication. Two methods are available: simple and signed requests. The basic method requires the addition of the key parameter as described in this page. The signed requests require the addition of a few HTTP headers (Content-MD5, Date, Authorization).

Batch Mode

Batch mode is useful for applications where paraphrases for several queries must be generated. In this mode the client can quickly send all the requests over a single connection and the server uploads the results when available. It works like this:

A drop box for the response documents must be setup.
The request message must contain parameter resultURI with a unique URI for each request.
The server validates the requests and returns HTTP "accepted" (202) for valid ones.
The server deposits at resultURI the same result as obtained in non-batch mode, i.e., a "Response" object with all the response elements.
If the request also contains notificationURI, the server sends a message to that SQS queue. The message contains the same "Response" object except output from parameter wsdMime.

Note: When not requesting the sense annotated results (i.e., parameter wsdMime is not specified), parameter notificationURI also triggers batch mode. This is simpler because no need to setup a dropbox. The SQS message includes the paraphrases.

Example

http(s)://api.idilia.com/1/text/paraphrase.xml?
  key=<your project value>&
  requestId=ac123&
  text=porch+lights&
  maxCount=5&
  textMime=text/query;+charset=utf8
<ParaphraseResponse>
 <status>200</status>
 <requestId>ac123</requestId>
 <paraphrases>
  <paraphrase><weight>1.00></weight><surface>porch lights</surface></paraphrase>
  <paraphrase><weight>0.69</weight><surface>deck lights</surface></paraphrase>
  <paraphrase><weight>0.69</weight><surface>veranda lights</surface></paraphrase>
 <paraphrases>
</ParaphraseResponse>

Disambiguation:		No known issues
Paraphrase:		No known issues
KB:		No known issues

Personal tools

Sections