Get Started

1. Get your API key

Begin with registering for an API key. The API key will instantaneously be sent to the email you registered with. Your keys is as important as a password and should be stored securely.

2. Authentication

To authenticate with the API you run the method auth.accessToken. If your API key and your Secret key (your key pair) is valid a token is created which you will use for further API calls.

//Request
{"method":"auth.accessToken","params":{"api_key":"d41d8cd98f00b204e9800998ecf8427e","secret_key":"74be16979710d4c4e7c6647856088456"}}

//Response
{"result":{"access_token":"AT1982711345265993464N"}}
SaploClient client = new SaploClient("YOUR_API_KEY", "YOUR_SECRET_KEY");

// Your access_token is stored in the client.
// If you want to retrieve it, you can
String accessToken = client.getAccessToken();
System.out.println(accessToken);
//When creating the SaploAPI object ($client) you will automatically be authenticated.
$client = new SaploAPI("YOUR API KEY", "YOUR SECRET KEY");

//You can also get your Access Token
echo $client->getAccessToken();
# When creating the SaploJSONClient object you will automatically be authenticated.
client = SaploJSONClient("YOUR API KEY", "YOUR SECRET KEY")
 
# You can also explicitly get your Access Token
print client.token
curl -d '{"method":"auth.accessToken","params":{"api_key":"API KEY","secret_key":"SECRET KEY"}}' 'http://api.saplo.com/rpc/json'

{"result":{"access_token":"AT8334226834920397662"}}
params.api_key = 'YOUR API KEY';
params.secret_key = 'YOUR SECRET KEY';
response = saploRequest('auth.accessToken', params);
response.access_token

Note: If you have built your own library all requests should be posted (POST) to endpoint http://api.saplo.com/rpc/json?access_token=TOKEN or if you prefer a secure connection, use https.

3. Create a text collection

To be able to extract information (Tags, Related Texts, Related Contexts etc.) from the API you first need to add some texts to the system. Texts are stored in text collections that you create. A collection can only contain text for a single language (e.g. only English texts).

Create your first text collection using the method collection.create.

//Request
{
  "method": "collection.create", 
  "params": {
    "name": "My Text Collection", 
    "description": "Collection for english blog posts", 
    "language": "en"
  }, 
  "id": 0
}

//Response
{
  "collection_id": 606,
  "description": "Collection for english blog posts",
  "name": "My Text Collection", 
  "language": "en",
  "next_id": 213
}
// First you need to create a manager to work with collections
SaploCollectionManager collectionMgr = new SaploCollectionManager(client);

// Then create a collection object
SaploCollection collection = new SaploCollection("My Collection Name", Language.en);

// Save the created collection in the API using the manager
collectionMgr.create(collection);
$client = new SaploAPI("YOUR API KEY", "YOUR SECRET KEY");

//Set parameters
$params = array(
    "name" => "My Collection",
    "description" => "This is my first collection for english texts.",
    "language" => "en"
);

//Run method
try {
    $result = $client->collection->create($params);
} catch(SaploException $e) {
    echo '(' . $e->getCode() . ') ' . $e->getMessage();
}

//Print result
var_dump($result);
client = SaploJSONClient("YOUR API KEY", "YOUR SECRET KEY")

collection_id = client.collection.create(
    name = "My Collection",
    description = "This is my first collection for english texts.",
    language = "en"
)

print "New collection created with Id:", collection_id
params.name = 'My First Collection';
params.language = 'en';
 
response = saploRequest('collection.create', params);
 
sprintf('Collection id %s \n', response.collection_id);

4. Add a text to a collection

After creating a collection you can start adding texts to it.

Add a text using the method text.create . When the text has been added it will get a unique id inside of that collection.

//Request
{
  "method":"text.create", 
  "params":{
      "body":"Hi this is my body text.",
      "collection_id":607
  }, 
  "id":0
}

//Response
{
  "id":0,
  "result":{
     "headline":"", 
     "url":"", 
     "collection_id":607,
     "text_id":1
  }
}
// First create a manager to work with text
SaploTextManager textMgr = new SaploTextManager(client);

// Then create a text object in your collection
SaploText text = new SaploText(collection, "Some cool text about Apple - the company, goes here");
text.setHeadline("Some cool headline");
text.setAuthors("Me");

// Then save your text using the manager
textMgr.create(text);
$client = new SaploAPI("YOUR API KEY", "YOUR SECRET KEY");

$params = array(
    "collection_id" => 1,
    "headline" => "This is my headline.",
    "body" => "This is my awesome body text which I am adding to Saplo API."
);

try {
    $result = $client->text->create($params);
} catch(SaploException $e) {
    echo '(' . $e->getCode() . ') ' . $e->getMessage();
}
 
var_dump($result);
client = SaploJSONClient("YOUR API KEY", "YOUR SECRET KEY")

text_id = client.text.create(
            collection_id=678,
            headline='Example Headline',
            body='This is a short example text. Insert a longer one for better results'
            )

print "New text created with Id:", text_id
params.headline = 'Sweden from Wikipedia';
params.body = 'Sweden shares borders with Norway to the west and Finland to the east, and is connected to Denmark by Öresund Bridge.';
params.collection_id = 2131;
 
response = saploRequest('text.create', params)
 
sprintf('Text id %s \n', response.text_id);

5. Get Entity Tags

Now that we have a text in our collection we can get entity tags from that text.

Get tags using the method text.tags.

//Request
{
  "method":"text.tags",
  "params":{
    "collection_id":607,
    "text_id":3,
    "wait":15
  },
  "id":0
}

//Response
{ 
 "id":0,
 "result":{
    "tags":[
        {
          "tag":"Saplo",
          "category":"organization",
          "relevance":1
        },
        {
          "tag":"Sweden",
          "category":"location",
          "relevance":0.81
        }
    ]
}
// Get a list of tags that exist in your text
List<SaploTag> tags = textMgr.tags(text);

// Print them out
for(SaploTag tag : tags)
    System.out.println("Category: " + tag.getCategory()
        + " TagWord: " + tag.getTagWord());
$client = new SaploAPI("YOUR API KEY", "YOUR SECRET KEY");

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

try {
    $result = $client->text->tags($params);
} catch(SaploException $e) {
    echo '(' . $e->getCode() . ') ' . $e->getMessage();
}
  
var_dump($result);
client = SaploJSONClient("YOUR API KEY", "YOUR SECRET KEY")

tags = client.text.tags(
            collection_id=678,
            text_id=2,
            wait=10
            )

print "Retrieved these tags from the text:", tags
params.collection_id = 2131;
params.text_id = 1;
params.wait = 10;
 
response = saploRequest('text.tags', params)

6. Get Related Texts

To be able to get related texts we need to add additional texts to the collection. When fetching related texts the API searches through the collection to find the texts that are most similar to each other. Lets add some more texts to our collection as we did in section 2.

Now we can search for related texts. To get related texts we run the method text.relatedTexts and specify the text id and collection id we want results for. The system will now index all texts and give return a list with results. In the result list you will find the related text id and the relevance which is a value between 0.0 and 1.0, a higher number indicating more relevance.

//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"
        },
        {
          "collection_id":607,
          "text_id":47,
          "headline":"Blogging is fun",
          "url":"www.saplo.com",
          "relevance":0.81,
          "publish_date":"2010-01-01T14:11:13Z"
        }
    ]
}
// Retrieve related texts to our given text
textMgr.relatedTexts(text);

// The related texts will be stored in your text object's relatedTexts element
List<SaploText> relatedList = text.getRelatedTexts();
for(SaploText relText : relatedList)
    System.out.println("TextId: " + relText.getId()
            + " relevance: " + relText.getRelatedRelevance()
            + " textHeadline: " + relText.getHeadline());
$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);
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
params.text_id = 1;
params.collection_id = 2131;
params.wait = 15;
 
response = saploRequest('text.relatedTexts', params)

7. Reset a Collection

Perhaps you’ve added some random texts or our example texts and now you want to get started for real. To start off from scratch with an empty collection you can use the method collection.reset. This will delete all texts and all results for that collection.
Remember, this can not be undone so be careful when using this method.

//Request
{
  "method":"collection.reset", 
  "params":{
    "collection_id":607
  }, 
  "id":0
}

//Response
{
  "collection_id": 607,
  "description": "Collection for english blog posts",
  "name": "My Text Collection", 
  "language": "en",
  "next_id": 1
}
// Use the collection manager's reset method,
// supplying it with the collection object
collectionMgr.reset(collection);
$client = new SaploAPI("YOUR API KEY", "YOUR SECRET KEY");

$params = array(
    "collection_id" => 1
);

try {
    $result = $client->collection->reset($params);
} catch(SaploException $e) {
    echo '(' . $e->getCode() . ') ' . $e->getMessage();
}
 
var_dump($result);
client = SaploJSONClient("YOUR API KEY", "YOUR SECRET KEY")

reset_collection = client.collection.reset(
                collection_id=678,
                )

print "Successfully reseted corpus with properties: ", reset_collection
params.collection_id = 2131;
  
response = saploRequest('collection.reset', params)

Congratulations! Now you know the basics for using Saplo API. To learn more check out our different tutorials.