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.

Post XML requests to API url (port 80):
http://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 xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
  <texts>
    <textBase64 id="text_1">SSBhbSBzbyBoYXBweSB0b2RheQ==</textBase64>
  </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.

Text Documents

The grouping texts can contain one or more textBase64 elements. Text documents should be base64 encoded to avoid that clients accidently break the xml.

Embedding a text

The element textBase64 contains a base64 encoded text. Those text elements are assigned an id, use this id to refer a text from your read and write calls.

NameTypeDescription
idRestrictedStringA unique identifier for this text.

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.

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

NameTypeDescription
idRestrictedStringA unique name for this call.
classifierNameRestrictedStringThe name of the classifier.
textIdRestrictedStringThe id of the text to classify, (refering to a textBase64 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 xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
  <texts>
    <textBase64 id="text_1">SSBhbSBzbyBoYXBweSB0b2RheQ==</textBase64>
  </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.195849"/>
      <class className="positive" p="0.804151"/>
    </classification>
  </classify>
  </readCalls>
</uclassify>

Extract keywords

The call classifyKeywords sends a text to a classifier and returns a classification plus relevant keywords for each class. If you need keywords for a text you should use classifyKeywords instead of classify (don't use both for the same text). The call itself uses the exact same arguments as the classify call.

NameTypeDescription
idRestrictedStringA unique name for this call.
classifierNameRestrictedStringThe name of the classifier.
textIdRestrictedStringThe id of the text to classify, (refering to a textBase64 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 xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
  <texts>
    <textBase64 id="text_1">SSBhbSBzbyBoYXBweSB0b2RheQ==</textBase64>
  </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">
    <classification textCoverage="1">
      <class className="negative" p="0.195849"/>
      <class className="positive" p="0.804151"/>
    </classification>
    <keywords>
      <class className="negative">today I am</class>
      <class className="positive">happy so</class>
    </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.

NameTypeDescription
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 xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
  <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>145310</uniqueFeatures>
          <totalCount>1962184</totalCount>
        </classInformation>
        <classInformation className="positive">
          <uniqueFeatures>180904</uniqueFeatures>
          <totalCount>2473001</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.

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

NameTypeDescription
idRestrictedStringA unique name for this call.
Creates a classifier named 'MySentiment'
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
 <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.

NameTypeDescription
idRestrictedStringA unique name for this call.
Creates the classifier named 'MySentiment'
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
 <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.

NameTypeDescription
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 xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
 <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.

NameTypeDescription
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 xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
 <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.

NameTypeDescription
idRestrictedStringA unique name for this call.
classNameRestrictedStringThe name of the class to train.
textIdRestrictedStringThe id of the text to train, (refering to a textBase64 element).
Trains the class called 'Positive' of the classifier 'MySentiment'
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
 <texts>
  <textBase64 id="text_1">SSBhbSBzbyBoYXBweS4=</textBase64>
 </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.

NameTypeDescription
idRestrictedStringA unique name for this call.
classNameRestrictedStringThe name of the class to untrain.
textIdRestrictedStringThe id of the text to untrain, (refering to a textBase64 element).
Untrains the class called 'Positive' of the classifier 'MySentiment'
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
 <texts>
  <textBase64 id="text_1">SSBhbSBzbyBoYXBweS4=</textBase64>
 </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.

NameTypeDescription
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. The id identifies the call in the request.

NameTypeDescription
idRestrictedStringThe unique id of the call - matches one of the calls in the request.

The classify element contains a classification.

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.195849"/>
      <class className="positive" p="0.804151"/>
    </classification>
  </classify>
  </readCalls>
</uclassify>

ClassifyKeywords response

The classifyKeywords element contains the classification and keyword data for a specific call. The id identifies the call in the request.

NameTypeDescription
idRestrictedStringThe unique id of the call - matches one of the calls in the request.
The classify element contains a classification and a keywords.
<?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">
    <classification textCoverage="1">
      <class className="negative" p="0.195849"/>
      <class className="positive" p="0.804151"/>
    </classification>
    <keywords>
      <class className="negative">today I am</class>
      <class className="positive">happy so</class>
    </keywords>
  </classifyKeywords>
  </readCalls>
</uclassify>

GetInformation response

The getInformation response contains information about a specific classifier.

NameTypeDescription
idRestrictedStringThe unique id of the call - matches one of the calls in the request.

The getInformation element contains a classes 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>145310</uniqueFeatures>
          <totalCount>1962184</totalCount>
        </classInformation>
        <classInformation className="positive">
          <uniqueFeatures>180904</uniqueFeatures>
          <totalCount>2473001</totalCount>
        </classInformation>
      </classes>
    </getInformation>
  </readCalls>
</uclassify>

Classification

Holds a list of class elements, each with a probability [0-1] of the classified document belonging to it. To find the most probable class, use the one with highest probability.

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

The classification element contains one or many class.

Class

This represents a class and the probability that the document belongs to it.

NameTypeDescription
classNameRestrictedStringThe name of the class.
pdoubleThe probability that the text belongs to this class.

Keywords

The keywords grouping is a list of keyword specific class elements. Each class element contains a space separated string of relevant keywords.

NameTypeDescription
classStringThe inner text is a space separated of the extracted relevant keywords
classNameRestrictedStringThe name of the class.

Classes

The classes grouping is a list of classInformation elements.

ClassInformation

The classInformation element describes a class.

NameTypeDescription
classNameRestrictedStringThe name of the class.
totalCountintTotal number of words the class is trained on.
uniqueFeaturesintThe number of unique words the class is trained on.

Write Responses

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

NameTypeDescription
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 http://api.uclassify.com
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
  <texts>
    <textBase64 id="tweet_0">SSBhbSBzbyBoYXBweSB0b2RheQ==</textBase64>
    <textBase64 id="tweet_1">VG9kYXkgaXMgYSBnb29kIGRheQ==</textBase64>
    <textBase64 id="tweet_2">WWVzdGVyZGF5IHdhcyBiYWQ=</textBase64>
    <textBase64 id="tweet_3">VG9tb3Jyb3cgd2lsbCBiZSBmaW5l</textBase64>
    <textBase64 id="tweet_4">SSBhbSBub3QgYSBiYWQgYm90</textBase64>
    <textBase64 id="tweet_5">VGhpcyBpcyBub3QgZnVu</textBase64>
    <textBase64 id="tweet_6">SSBsb3ZlIGhlciBzbyBtdWNo</textBase64>
    <textBase64 id="tweet_7">SW5kZWVkIHdlIGFyZSBjb29s</textBase64>
    <textBase64 id="tweet_8">U3Vubnkgc3VuIHNoaW5lIG9u</textBase64>
    <textBase64 id="tweet_9">TmljZSBwYW50cyE=</textBase64>
  </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>

Creating a sentiment classifier step-by-step

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 http://api.uclassify.com
    <?xml version="1.0" encoding="utf-8" ?>
    <uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
     <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 http://api.uclassify.com
    <?xml version="1.0" encoding="utf-8" ?>
    <uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
     <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 http://api.uclassify.com
    <?xml version="1.0" encoding="utf-8" ?>
    <uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
     <texts>
      <textBase64 id="positive_text">SSBhbSBzbyBoYXBweQ==</textBase64>
      <textBase64 id="negative_text">SSBhbSBzbyBzYWQ=</textBase64>
     </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 http://api.uclassify.com
    <?xml version="1.0" encoding="utf-8" ?>
    <uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
      <texts>
        <textBase64 id="positive_text">SSBhbSBzbyBoYXBweQ==</textBase64>
        <textBase64 id="negative_text">SSBhbSBzbyBzYWQ=</textBase64>
      </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 http://api.uclassify.com
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
 <texts>
  <textBase64 id="Klingon1">SklsYWpuZVMuIGdoSWogcWV0IGphZ2htZXlqYWo=</textBase64>
  <textBase64 id="Klingon2">J2UnIHBhJyBqYWogbGF3JyBtbycgamFqIHB1Uw==</textBase64>
  <textBase64 id="Klingon3">J2VqIERvcSwgU29EdGFILCBnaG9TdGFIIFNJUWFs</textBase64>
  <textBase64 id="Sindarin1">SW5nb24gaSBhdGhyYWQgZGFtbWVuIGJlcmlhdGhhciBhZW4=</textBase64>
  <textBase64 id="Sindarin2">SG9uIG1hYmF0aG9uLiBSb2Nob24gZWxsaW50IGlt</textBase64>
  <textBase64 id="Sindarin3">TGFzdG8gQ2FyYWhkcmFzLCBzZWRobywgaG9kbw==</textBase64>
  <textBase64 id="Huttese1">S2FhIGJhenphIGt1bmRlZSBob2RydWRkYQ==</textBase64>
  <textBase64 id="Huttese2">U3Bhc3RlZWx5YSBib29raWUgb29raWU=</textBase64>
  <textBase64 id="Huttese3">TWUgZHdhbmEgbm8gYmF0YQ==</textBase64>
 </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 http://api.uclassify.com
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
 <texts>
  <textBase64 id="Klingon">J2F5J3ZhbURhcSBudUhtZXkgdElRZXE=</textBase64>
  <textBase64 id="Sindarin">b3N0byBDYXJhZGhhcmFzLCBzZWRobywgaG9kbywgbnVpdGhv</textBase64>
  <textBase64 id="Huttese">SCdjaHUgYXBlbmtlZQ==</textBase64>
 </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 http://api.uclassify.com
<?xml version="1.0" encoding="utf-8" ?>
<uclassify xmlns="http://api.uclassify.com/1/RequestSchema" version="1.01">
  <texts>
    <textBase64 id="UnknownFantasyText1">SXcgYklRdHFEYXEgYklsZW5namFq</textBase64>
    <textBase64 id="UnknownFantasyText2">UGFkb2wgcmFpZCwgYXRoYW4gaGVuZGFk</textBase64>
  </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("http://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('http://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: http://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 textBase64 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.