text.relatedTexts

Search a collection for related texts.
Returns a JSONArray named "related_texts" containing the result objects.

Request Parameters

collection_idint (required)
Collection id where your text is stored.
text_idint (required)
Id of the text to which you want to find other related texts.
related_byString (default: automatic)

How the texts should be related.
"automatic" - The engine automatically choose the best way.
"semantic" - Searching for texts based on the same semantic meaning.
"statistic" - Searching for texts based on statistical relations. E.g. number of words, similar words, common words etc.

collection_scopeint/array (default: Same as collection_id)
Search the given collection id(s) to find related texts. (To search in other collections than your source "collection_id" is a premium feature).
waitint (default: 5)

Maximum time you want to wait for a result to be calculated. Maximum wait time is 60 sec. If wait time is zero (0) you will only start the process and disconnect and can check out the result later. An exception will be thrown saying processing request. (See Error Codes)

limitint (default: 10)

The maximum number of related texts you want in your result. There is no guarantee that the number of results will equal the limit. Max 50.

min_thresholddecimal (default: 0.0)
If you only want related texts that are 50 % like your source text, provide 0.5 as parameter.
max_thresholddecimal (default: 1.0)
If you only want related texts that has a relevance to the source text to a max of 90 %, provide 0.9 as parameter.
ext_text_idString

The external id of the text to which you want to find other related texts. If this variable is set you can skip text_id parameter.

text_scopeArray (Int)
Define which texts you want to compare against. (can only compare against the same collection)

Response Parameters

collection_idint
Collection id for related text.
text_idint
Id for related text.
relevancedecimal

Relevance value between 0.0-1.0.
1.0 is the exact same text.

publish_dateString
Date when text was published. Set when text was created.
headlineString
Headline of related text.
urlString
URL of related text.
ext_text_idString

External text id.

Code Examples

JSON

//Request
{
  "method":"text.relatedTexts", 
  "params":{
    "collection_id":607, 
    "text_id":758
  }, 
  "id":0
}


//Response
{ 
 "id":0,
 "result":{
    "related_texts":[
        {
          "collection_id":607,
          "text_id":6310,
          "headline":"Getting started",
          "url":"www.saplo.com",
          "relevance":0.91,
          "publish_date":"2010-01-01T12:11:13Z",
          "ext_text_id":"23190821"
        },
        {
          "collection_id":607,
          "text_id":47,
          "headline":"Blogging is fun",
          "url":"www.saplo.com",
          "relevance":0.81,
          "publish_date":"2010-01-01T14:11:13Z",
          "ext_text_id":"DF-131-XS"
        }
    ]
}

Java


// You need to have a ready-to-use client to use the other methods
SaploClient client = new SaploClient("YOUR_API_KEY", "YOUR_SECRET_KEY");

// Create a SaploTextManager to work with texts
SaploTextManager textMgr = new SaploTextManager(client);

// Assuming you already have collection the text belongs to and the text ID 
SaploText text = new SaploText();
text.setCollection(collection);
text.setId(textId);

// Find texts that are related to the text in the same collection
textMgr.relatedTexts(text);

// The related texts can now be retrieved by .getRelatedTexts(); 
// on the text object
// Print the result
for(SaploText related : text.getRelatedTexts())
    System.out.println("Related text Id: " + related.getId() 
        + " relevance: " + related.getRelatedRelevance());

PHP


$client = new SaploAPI("YOUR API KEY", "YOUR SECRET KEY");

$params = array(
    "collection_id" => 15,
    "text_id" => 1
);

try {
    $result = $client->text->related_texts($params);
} catch(SaploException $e) {
    echo '(' . $e->getCode() . ') ' . $e->getMessage();
}
  
var_dump($result);

Python


client = SaploJSONClient("YOUR API KEY", "YORU SECRET KEY")

related_texts = client.text.related_texts(
            collection_id=678,
            text_id=1,
            wait=30
            )

print "Related texts:", related_texts

Matlab

params.text_id = 1;
params.collection_id = 2131;
params.wait = 15;

response = saploRequest('text.relatedTexts', params)