API Overview

Our hope is to provide an easy-to-use API using xml requests. When a request is done to the web API, a response is returned. The response will tell you if the request was successful and return whatever is relevant for your calls. Below, XML attributes are denoted by a @ before its name, e.g. @id.

https://api.uclassify.com

Getting started

The XML api is very powerful, it allows you to batch calls to the server, running texts through different classifiers, yours and other users. However, the most common use is to classify one text with one classifier, to do this use the classify call.

Example request

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="text_1">I am happy sad bad</text>
  </texts>
  <readCalls readApiKey="YOUR_READ_API_KEY_HERE">
    <classify id="call_1" username="uClassify" classifierName="Sentiment" textId="text_1" />
  </readCalls>
</uclassify>

RestrictedString data type

Most attributes in the API accepts RestrictedString, which essentially is a string that is limited to a-Z space _ and 0-9.

Texts

The grouping texts contains one or more text elements.

Select classifier language

The texts element may specify the language of the embedded texts with the optional language attribute.

Multilingual classifiers will show a list of available languages above the description. E.g. see the Sentiment classifier.

Here is an example classifying a Spanish text on sentiment.

Embedding a text

The element text contains a XML encoded text. Those text elements are assigned an id, use this id to refer a text from your read and write calls. To avoid breaking the XML the text should be XML encoded, most programming languages has support for this.

We still support the legacy way, which is to pass the string base64 encoded in the textBase64 element.

Read Calls

The grouping readCalls can hold one or more classify, classifyKeywords and getInformation calls. Each read call can reference different classifiers and texts. Each call is executed in a sequential order.

Classify a text

The call classify sends a text to a classifier and returns a classification. The default behaviour is to access classifiers in the same account as the readApiKey given in the readCalls parent element. You can access published classfieirs from other users (accounts) by setting the optional username attribute to that classifiers author.

Returns a classify response.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="text_1">I am happy sad bad</text>
  </texts>
  <readCalls readApiKey="YOUR_READ_API_KEY_HERE">
    <classify id="call_1" username="uClassify" classifierName="Sentiment" textId="text_1" />
  </readCalls>
</uclassify>

<?xml version="1.0" encoding="UTF-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.01">
  <status success="true" statusCode="2000"/>
  <readCalls>
  <classify id="call_1">
    <classification textCoverage="1">
      <class className="negative" p="0.628401"/>
      <class className="positive" p="0.371599"/>
    </classification>
  </classify>
  </readCalls>
</uclassify>

Extract keywords

The call classifyKeywords sends a text to a classifier and returns a list relevant keywords for each call. The call itself uses the exact same arguments as the classify call.

Returns a classifyKeywords response.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="text_1">I am happy sad bad</text>
  </texts>
  <readCalls readApiKey="YOUR_READ_API_KEY_HERE">
    <classifyKeywords id="call_1" username="uClassify" classifierName="Sentiment" textId="text_1" />
  </readCalls>
</uclassify>

<?xml version="1.0" encoding="UTF-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.01">
  <status success="true" statusCode="2000"/>
  <readCalls>
  <classifyKeywords id="call_1">
    <keywords>
      <keyword className="positive" p="0.698998">happy</keyword>
      <keyword className="negative" p="0.736395">bad</keyword>
      <keyword className="negative" p="0.788017">sad</keyword>
    </keywords>
  </classifyKeywords>
  </readCalls>
</uclassify>

Get classifier information

The call getInformation fetches information about a classifier. It lists the classes and on how many features they have been trained.

Returns a getInformation response.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <readCalls readApiKey="YOUR_READ_API_KEY_HERE">
    <getInformation id="call_1" username="uClassify" classifierName="Sentiment" />
  </readCalls>
</uclassify>

<?xml version="1.0" encoding="UTF-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.01">
  <status success="true" statusCode="2000"/>
  <readCalls>
    <getInformation id="call_1">
      <classes>
        <classInformation className="negative">
          <uniqueFeatures>6832265</uniqueFeatures>
          <totalCount>208068140</totalCount>
        </classInformation>
        <classInformation className="positive">
          <uniqueFeatures>6607607</uniqueFeatures>
          <totalCount>180593163</totalCount>
        </classInformation>
      </classes>
    </getInformation>
  </readCalls>
</uclassify>

Write Calls

The grouping writeCalls allow you to create and remove classifiers, add classes and remove classes, train and untrain. It can hold one or more write call. Each call is executed in a sequential order. All write calls will operate on the same classifier.

Create classifier

The call create creates a classifier for the account associated with the write API key. The name of the new classifier is the classifierName set in the writeCalls grouping.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
    <create id="call_1" />
  </writeCalls>
</uclassify>

Remove classifier

The call remove removes the classifier for the account associated with the write API key. The name of the new classifier is the classifierName set in the writeCalls grouping.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
    <remove id="call_1" />
  </writeCalls>
</uclassify>

Add class

The call addClass adds a class to a classifier.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
    <addClass id="call_1" className="Positive" />
  </writeCalls>
</uclassify>

Remove class

The call removeClass removes a class from the classifier.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
    <removeClass id="call_1" className="Positive" />
  </writeCalls>
</uclassify>

Train classifier

The call train trains a class in the classifier on a text.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="text_1">I am so happy.</text>
  </texts>
  <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
    <train id="call_1" className="Positive" textId="text_1" />
  </writeCalls>
</uclassify>

Untrain classifier

The call untrain untrains the classifier on a text for a specified class. The common usage for this call is to correct misstakes, if you train a classifier on a text and then untrain it on the same text the classifier will returned to the previous state. For example if a spam message incorrectly is trained as a legitimate - use this call to fix the misstake by untraining the spam message from the legitimate class and then training it (train call) on the spam class.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="text_1">I am so happy.</text>
  </texts>
  <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
    <untrain id="call_1" className="Positive" textId="text_1" />
  </writeCalls>
</uclassify>

Read responses

All responses has status, success and a statusCode. The inner text of the status will contain any error message.

A readCalls grouping holds a list of all calls, one for each call.

Classify response

The classify element contains the classification data for a specific call, identified by its id attribute (same as in the request). Classification holds a list of class elements, each with a class name and probability [0-1] of the classified document belonging to it. To find the most probable class, use the one with highest probability.

<?xml version="1.0" encoding="UTF-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.01">
  <status success="true" statusCode="2000"/>
  <readCalls>
  <classify id="call_1">
    <classification textCoverage="1">
      <class className="negative" p="0.628401"/>
      <class className="positive" p="0.371599"/>
    </classification>
  </classify>
  </readCalls>
</uclassify>

ClassifyKeywords response

The classifyKeywords element contains the a list of keywords for a specific call, identified by its id attribute (same as in the request). Keyword elements are denoted by keyword and contains the keyword, its probability (weight) and the relevant class name.

<?xml version="1.0" encoding="UTF-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.01">
  <status success="true" statusCode="2000"/>
  <readCalls>
  <classifyKeywords id="call_1">
    <keywords>
      <keyword className="positive" p="0.698998">happy</keyword>
      <keyword className="negative" p="0.736395">bad</keyword>
      <keyword className="negative" p="0.788017">sad</keyword>
    </keywords>
  </classifyKeywords>
  </readCalls>
</uclassify>

GetInformation response

The getInformation response contains information about a specific classifier. The classes element is a list of all classes each containing information about the class itself in its classInformation element.

<?xml version="1.0" encoding="UTF-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.01">
  <status success="true" statusCode="2000"/>
  <readCalls>
    <getInformation id="call_1">
      <classes>
        <classInformation className="negative">
          <uniqueFeatures>6832265</uniqueFeatures>
          <totalCount>208068140</totalCount>
        </classInformation>
        <classInformation className="positive">
          <uniqueFeatures>6607607</uniqueFeatures>
          <totalCount>180593163</totalCount>
        </classInformation>
      </classes>
    </getInformation>
  </readCalls>
</uclassify>

Write Responses

All responses has status, success and a statusCode. The inner text of the status will contain any error message.

There are no additional response data for write calls.

<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.01">
	<status success="true" statusCode="2000" />
</uclassify>

<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.00">
	<status success="false" statusCode="4000">Could not find the classifier to train.</status>
</uclassify>

Examples

The following are examples of how you can use the API to programmatically create classifiers. Remember that all of this is also possible via our gui!

Twitter sentiment

This shows how to batch multiple texts in one request. In this case it's 10 tweets that are classified for sentiment

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="tweet_0">I am so happy today</text>
    <text id="tweet_1">Today is a good day</text>
    <text id="tweet_2">Yesterday was bad</text>
    <text id="tweet_3">Tomorrow will be fine</text>
    <text id="tweet_4">I am not a bad bot</text>
    <text id="tweet_5">This is not fun</text>
    <text id="tweet_6">I love her so much</text>
    <text id="tweet_7">Indeed we are cool</text>
    <text id="tweet_8">Sunny sun shine on</text>
    <text id="tweet_9">Nice pants!</text>
  </texts>
  <readCalls readApiKey="YOUR_READ_API_KEY_HERE">
    <classify id="call_0" username="uClassify" classifierName="Sentiment" textId="tweet_0" />
    <classify id="call_1" username="uClassify" classifierName="Sentiment" textId="tweet_1" />
    <classify id="call_2" username="uClassify" classifierName="Sentiment" textId="tweet_2" />
    <classify id="call_3" username="uClassify" classifierName="Sentiment" textId="tweet_3" />
    <classify id="call_4" username="uClassify" classifierName="Sentiment" textId="tweet_4" />
    <classify id="call_5" username="uClassify" classifierName="Sentiment" textId="tweet_5" />
    <classify id="call_6" username="uClassify" classifierName="Sentiment" textId="tweet_6" />
    <classify id="call_7" username="uClassify" classifierName="Sentiment" textId="tweet_7" />
    <classify id="call_8" username="uClassify" classifierName="Sentiment" textId="tweet_8" />
    <classify id="call_9" username="uClassify" classifierName="Sentiment" textId="tweet_9" />
  </readCalls>
</uclassify>

Sentiment classifier in Spanish

This shows how to use the Spanish version of the sentiment classifier, only difference is the use of the language attribute in the texts element.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts language="es">
    <text id="text_1">estoy tan feliz hoy</text>
  </texts>
  <readCalls readApiKey="YOUR_READ_API_KEY_HERE">
    <classify id="call_1" username="uClassify" classifierName="Sentiment" textId="text_1" />
  </readCalls>
</uclassify>

Creating a sentiment classifier step-by-step

To use the already existing sentiment classifier, please see the sentiment example above. However, if you wish to create your own, maybe in another language or just study how to create custom classifiers, please read on!

Let's say that you want to create a web site that finds out whether a text is positive or negative. The first steps you take are

1. Register and get a free uClassify account
2. Under the tab 'Api Keys' obtain your read and write keys

Now you have an account and can use your write API key to programatically create classifiers. Before you create a classifier, you must come up with a name for it. Let's call it 'MySentiment'.

3. Create the new classifier, 'MySentiment'
   Send the following POST request to https://api.uclassify.com

   <?xml version="1.0" encoding="utf-8"?>
   <uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
     <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
       <create id="call_1" />
     </writeCalls>
   </uclassify>

The request simply creates a classifier named 'MySentiment' using the write call create. The id attribute is set to an arbitrary identifier for that call. Each request sends back an xml response, informing you if the request was successful or not. You can now log in to your account and be able to find a classifier called 'ManOrWoman' under the 'Classifiers' tab. The next thing to do is to add the possible classes. In our sentiment classifier there are two classes, 'Positive' and 'Negative'.

4. Add classes to 'MySentiment'
   Send the following POST request to https://api.uclassify.com

   <?xml version="1.0" encoding="utf-8"?>
   <uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
     <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
       <addClass id="call_1" className="Positive" />
       <addClass id="call_2" className="Negative" />
     </writeCalls>
   </uclassify>

Before we can start using the classifier we need to train it. To do this we need collect training data for each class. In this case it would be a bunch of positive texts and negative. For simplicity of this example we train it on one short message per class.

5. Train the classes in 'MySentiment'
   Send the following POST request to https://api.uclassify.com

   <?xml version="1.0" encoding="utf-8"?>
   <uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
     <texts>
       <text id="positive_text">I am so happy</text>
       <text id="negative_text">I am so sad</text>
     </texts>
     <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="MySentiment">
       <train id="call_1" className="Positive" textId="postive_text" />
       <train id="call_2" className="Negative" textId="negative_text" />
     </writeCalls>
   </uclassify>

Note that the texts have been base64 encoded so they don't break the xml. Of course it would need more training than two short texts to give good results. You can repeat this process (automate it) or batch many texts in the same request. When training is done it's time to start classifying using the read API key. Add a form to your web site where visitors can insert texts or links. When the form button is pressed send a POST request to classify the text.

6. Send a request with a text to find out if it's positive or negative
   Send the following POST request to https://api.uclassify.com

   <?xml version="1.0" encoding="utf-8"?>
   <uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
     <texts>
       <text id="positive_text">I am so happy</text>
       <text id="negative_text">I am so sad</text>
     </texts>
     <readCalls readApiKey="YOUR_READ_API_KEY_HERE">
       <classify id="call_1" classifierName="MySentiment" textId="postive_text" />
       <classify id="call_2" classifierName="MySentiment" textId="negative_text" />
     </readCalls>
   </uclassify>

Creating a fantasy language classifier

This shows how to create a classifier that distinguishes text between the classes Klingon, Sindarin and Huttese. This is done in one request, however it's possible to split it into one for each call, or any number. And of course it's possible (and necessary) to continue training the classifier with more texts for each fantasy language.

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="Klingon1">JIlajneS. ghIj qet jaghmeyjaj</text>
    <text id="Klingon2">'e' pa' jaj law' mo' jaj puS</text>
    <text id="Klingon3">'ej Doq, SoDtaH, ghoStaH SIQal</text>
    <text id="Sindarin1">Ingon i athrad dammen beriathar aen</text>
    <text id="Sindarin2">Hon mabathon. Rochon ellint im</text>
    <text id="Sindarin3">Lasto Carahdras, sedho, hodo</text>
    <text id="Huttese1">Kaa bazza kundee hodrudda</text>
    <text id="Huttese2">Spasteelya bookie ookie</text>
    <text id="Huttese3">Me dwana no bata</text>
  </texts>
  <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="FantasyLanguage">
    <create id="create" />
    <addClass id="add1" className="Klingon" />
    <addClass id="add2" className="Sindarin" />
    <addClass id="add3" className="Huttese" />
    <train id="train1" className="Klingon" textId="Klingon1" />
    <train id="train2" className="Klingon" textId="Klingon2" />
    <train id="train3" className="Klingon" textId="Klingon3" />
    <train id="train4" className="Sindarin" textId="Sindarin1" />
    <train id="train5" className="Sindarin" textId="Sindarin2" />
    <train id="train6" className="Sindarin" textId="Sindarin3" />
    <train id="train7" className="Huttese" textId="Huttese1" />
    <train id="train8" className="Huttese" textId="Huttese2" />
    <train id="train9" className="Huttese" textId="Huttese3" />
  </writeCalls>
</uclassify>

Requests to train it further could look like this

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="Klingon">'ay'vamDaq nuHmey tIQeq</text>
    <text id="Sindarin">osto Caradharas, sedho, hodo, nuitho</text>
    <text id="Huttese">H'chu apenkee</text>
  </texts>
  <writeCalls writeApiKey="YOUR_WRITE_API_KEY_HERE" classifierName="FantasyLanguage">
    <train id="train1" className="Klingon" textId="Klingon" />
    <train id="train2" className="Sindarin" textId="Sindarin" />
    <train id="train3" className="Huttese" textId="Huttese" />
  </writeCalls>
</uclassify>

When training is done, a classify request with two unclassified texts could look like this

<?xml version="1.0" encoding="utf-8"?>
<uclassify version="1.01" xmlns="http://api.uclassify.com/1/RequestSchema">
  <texts>
    <text id="UnknownFantasyText1">Iw bIQtqDaq bIlengjaj</text>
    <text id="UnknownFantasyText2">Padol raid, athan hendad</text>
  </texts>
  <readCalls readApiKey="YOUR_READ_API_KEY_HERE">
    <classify id="Classify1" classifierName="FantasyLanguage" textId="UnknownFantasyText1" />
    <classify id="Classify2" classifierName="FantasyLanguage" textId="UnknownFantasyText2" />
  </readCalls>
</uclassify>

Post Requests

Here are some snippets to show how to programmatically make post requests from different languages:

Posting from C#

public string Post(string xml)
{
    var builder = new UriBuilder("https://api.uclassify.com/");
    var url = builder.Uri;
    var request = (HttpWebRequest) WebRequest.Create(url);
    request.Method = "Post";
    request.ContentType = "text/XML";
    using (var writer = new StreamWriter(request.GetRequestStream()))
    {
        writer.Write(xml);
    }
    using (var response = (HttpWebResponse) request.GetResponse())
    {
        using (var reader = new StreamReader(response.GetResponseStream()))
        {
            return reader.ReadToEnd();
        }
    }
}

Posting from Java

todo

Posting from PHP

function postRequest($xmlRequest)
{
    $params = array('http' =>
    array(
       'method' => 'POST',
       'header' => 'Content-Type: text/xml; charset=utf-8',
       'content' => $xmlRequest));
    $ctx = stream_context_create($params);
    $fp = @fopen('https://api.uclassify.com', 'rb', false, $ctx);
    if (!$fp)
        return false;
    $xmlResponse = @stream_get_contents($fp);
    @fclose($fp);
    return $xmlResponse;
}

Details

This section presents more in depth information about the web API.

Requests

Each request can contain an unlimited number of calls (as long as it follows the restrictions mentioned below). Requests can consist of either read calls or write calls, but not both in the same request. At this point classify, classifyKeyword, getInformation are read calls. Write calls include create, remove, addClass, removeClass, train and untrain. Each call has an id attribute, set this attribute to a unique string that helps you identify it in the response e.g. (<create id="MyCreateCall">). Calls within the readCalls and writeCalls element are executed sequentially. Post xml encoded requests to the API url: https://api.uclassify.com (port 80)

Responses

All responses returns a status element, the status element has a boolean attribute called success and if this is true the request went through without any trouble. If it's false something went wrong, in this case the status element inner text will contain an error message (e.g. <status success="false" statuscode="3000">The classifier 'MySpamClassifier' doesn't exist.</status >). A real error message will also indicate which call failed using its unique id attribute. For now the only call that returns something more than the status is the classify call.

Flexibility

The API is designed to handle multiple calls in each request; this means that you are able to batch multiple texts to one or many classifiers in the same call. This is extremely powerful, say if you want to classify 300 blog posts, you can send each in a text element, and in each classify call specify a text to classifier mapping. This is done by indexing texts from classify calls. Also when training this is useful, you can send a bulk of training texts to a classifier. Note that requests to modify classifiers can only be done on one classifier per request.

Transactional behaviour

If one of the write calls goes wrong, all previous successful calls in the request are rollbacked, meaning that the classifier is guaranteed to be in the same state as prior to processing the request. This is to prevent leaving classifiers in an undefined state.

Restrictions

Each xml request can at a maximum be 1MB. Every request must conform to our xml schema. All attributes that is of the type 'RestrictedString' is restricted to a-Z, space and 0-9.

Encoding

It's important that the encoding (ASCII, UTF-8, Unicode, ANSI etc) of the training documents are the same as the documents being classified (the classifier doesn't differentiate between the encodings internally). It's possible to mix encodings (requires more training data), however, we recommend that you make sure that you train and classify on the same encoding. What encoding you use is up to you.

Xml Schemas and Namespaces

The API strictly follows an xml schema; any violation will result in an erroneous response indicating what you need to fix in the request. Schemas validates the xml, that it follows a set of rules. By putting the xml into a namespace, it ensures that there are not datatype conflicts, e.g. we can have many 'string' types as long as they are in different namespaces. The namespace is set in the xmlns attribute of the root element (uclassify),

• The xml request namespace is https://api.uclassify.com/1/RequestSchema
• The xml response namespace is https://api.uclassify.com/1/ResponseSchema
• The xml request schema is https://api.uclassify.com/1/RequestSchema
• The xml response schema is https://api.uclassify.com/1/ResponseSchema

We know (by experience) that namespaces can be confusing, please let us know if you think this is the case so we can improve the API.

API Versions

When something changes in the API a new version is added in order to maintain compatibility with current API users. This means that users explicitly need to bump their request versions to use the latest API version. The version is specified as an attribute in the <uclassify> tag. Version 1.01 added the textCoverage score.