XML API

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.

Post XML requests to API url (port 443):
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, todo this use the classify call.

Example request

To classify a text with the uClassify sentiment classifier
<?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 classifier language is still in BETA and may be subject of unannounced changes.

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.

Name Type Description
@languageRestrictedString(optional) Possible values are 'en' (English), 'es' (Spanish), 'fr' (French) or 'sv' (Swedish). If not set the classifier default language is assumed (usually English). This attribute is only valid for 'Classify' calls.

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.

Name Type Description
@idRestrictedStringA unique identifier for this text.

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.

Name Type Description
@readApiKeyRestrictedStringYour read api key.

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.

Name Type Description
@idRestrictedStringA unique name for this call.
@classifierNameRestrictedStringThe name of the classifier.
@textIdRestrictedStringThe id of the text to classify, (refering to a text element).
@usernameRestrictedString(optional) Use this to identify a public classifier that is not owned by you. Set this to the username of the classifiers creator.

Returns a classify response.

This example shows how you can access a classifier that is public and not owned by yourself. Note the use of the username argument.
<?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 response
<?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.

Name Type Description
@idRestrictedStringA unique name for this call.
@classifierNameRestrictedStringThe name of the classifier.
@textIdRestrictedStringThe id of the text to classify, (refering to a text element).
@usernameRestrictedString(optional) Use this to identify a public classifier that is not owned by you. Set this to the username of the classifiers creator.

Returns a classifyKeywords response.

This example shows how you can extract keywords from the sentiment classifier.
<?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>
And this is the XML response
<?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.788017">sad</keyword>
      <keyword className="negative" p="0.736395">bad</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.

Name Type Description
@idRestrictedStringA unique name for this call.
@classifierNameRestrictedStringThe name of the classifier.
@usernameRestrictedString(optional) Use this to identify a public classifier that is not owned by you. Set this to the username of the classifiers creator.

Returns a getInformation response.

This show how to get information from a classifier.
<?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>
And this is the XML response
<?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.

Name Type Description
@writeApiKeyRestrictedStringA write API key that has access to the specified classifier.
@classifierNameRestrictedStringThe name of the classifier that you wish to modify or create.

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.

Name Type Description
@idRestrictedStringA unique name for this call.
Creates a classifier named 'MySentiment'
<?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.

Name Type Description
@idRestrictedStringA unique name for this call.
Removes the classifier named 'MySentiment'
<?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.

Name Type Description
@idRestrictedStringA unique name for this call.
@classNameRestrictedStringThe name of the class to add.
Adds a class called 'Positive' to the classifier 'MySentiment'
<?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.

Name Type Description
@idRestrictedStringA unique name for this call.
@classNameRestrictedStringThe name of the class to remove.
Removes the class called 'Positive' from the classifier 'MySentiment'
<?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.

Name Type Description
@idRestrictedStringA unique name for this call.
@classNameRestrictedStringThe name of the class to train.
@textIdRestrictedStringThe id of the text to train, (refering to a text element).
Trains the class called 'Positive' of the classifier 'MySentiment'
<?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.

Name Type Description
@idRestrictedStringA unique name for this call.
@classNameRestrictedStringThe name of the class to untrain.
@textIdRestrictedStringThe id of the text to untrain, (refering to a text element).
Untrains the class called 'Positive' of the classifier 'MySentiment'
<?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.

Name Type Description
statusstringThe inner text contains any error message.
@successboolTrue if the request was successful, false if not.
@statusCodeint 2000=OK, 4000=BAD_REQUEST, 4013=REQUEST_ENTITY_TOO_LARGE, 5000=INTERNAL_SERVER_ERROR, 5030=SERVICE_UNAVAILABLE

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.

Name Type Description
@idRestrictedStringThe unique id of the call - matches one of the calls in the request.
@textCoveragedoubleThe propotion of the classified text that was found in the training data. 1 means that every word was used, 0 that no words were used. Useful to determine the relevance of the classification. Available from api version 1.01.
@classNameRestrictedStringThe name of the class.
@pdoubleThe probability that the text belongs to this class.
Example of two successful classify calls to a spam classifier
<?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.

Name Type Description
@idRestrictedStringThe unique id of the call - matches one of the calls in the request.
@classNameRestrictedStringThe name of the class.
@pdoubleThe probability (weight) of the keyword, higher value means a more important word.
<?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.788017">sad</keyword>
      <keyword className="negative" p="0.736395">bad</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.

Name Type Description
@idRestrictedStringThe unique id of the call - matches one of the calls in the request.
@classNameRestrictedStringThe name of the class.
totalCountintTotal number of words the class is trained on.
uniqueFeaturesintThe number of unique words the class is trained on.
<?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.

Name Type Description
statusstringThe inner text contains any error message.
successboolTrue if the request was successful, false if not.
statusCodeint 2000=OK, 4000=BAD_REQUEST, 4013=REQUEST_ENTITY_TOO_LARGE, 5000=INTERNAL_SERVER_ERROR, 5030=SERVICE_UNAVAILABLE

There are no additional response data for write calls.

Successful response
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/ResponseSchema" version="1.01">
	<status success="true" statusCode="2000" />
</uclassify>
Something went wrong
<?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

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="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.

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 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'.

  1. 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'.

  1. 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.

  1. 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.

  1. 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.

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="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

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="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

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="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),

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.