The public interface of the service publishes a set of predefined classifier.

Classification requests are limited to a maximum hourly rate. The counter for the limit is reset every hour.

• Main API description
• Code example

API

The public interface of the classification service publishes two methods, info and classify.

${classifier_path}info

The info method returns a list of the available classifiers, each represented by a dictionary with the following keys:

• name - name of the classifier
• type - type of the classifier, i.e., a name that indicates the type of machine learning algorithm on which the classifier is based. Current classifier types are <%! from ics.db import sqlalchemydb %> % for classifier_type in sqlalchemydb.ClassificationMode: "${classifier_type.value}" % endfor .
• labels - a list of the labels from which the classifier picks the one to assign to a piece of text.
• created - the time of creation of the classifier
• updated - the time of last update of the classifier
• size - an estimate of the training set size for the classifier (could be even zero if a classifier is loaded pretrained)

Example of query and output:

            Query:
                ${classifier_path}info

            Response:
                [{
                    "name": "demo",
                    "type": "Single-label",
                    "labels": ["yes", "no"],
                    "created": "2018-04-06 11:18:38.096562+02:00",
                    "updated": "2018-04-06 11:18:45.118769+02:00",
                    "size": 10
                },
                {"name": "demo2",
                    "type": "Multi-label",
                    "labels": ["car", "bike", "bus", "walk"],
                    "created": "2018-04-06 11:18:38.096562+02:00",
                    "updated": "2018-04-06 11:18:45.118769+02:00",
                    "size": 100
                }]
        

test info query

${classifier_path}classify

The classify method take input the name of a classifier and one or more strings of text X and returns a list of the labels assigned by the classifier to each string of text. The order of the labels follows the order of the strings in the query. If a classifier named name does not exist, a error 500 will be returned.

Example of query and output:

            Query:
                ${classifier_path}classify?name=demo&X='this is a test'
            Output:
                ["yes"]

            Query:
                ${classifier_path}classify?name=demo&X='this is not a test'
            Output:
                ["no"]

            Query:
                ${classifier_path}classify?name=demo&X='this is a test'&X='this is not a test'
            Output:
                ["yes", "no"]

            Note that this last query counts as two classification requests.
        

Code

This is an example of code to query the service. It also shows how to use authorization keys and how to query for the usage stats:

import json

import requests
from requests import HTTPError

__author__ = 'Andrea Esuli'


class ServiceDemoClient:
    def __init__(self, protocol, host, port, classifier_path, ip_auth_path, key_auth_path):
        self._protocol = protocol
        self._host = host
        if type(port) == int:
            port = str(port)
        self._port = port
        self._classifier_path = classifier_path
        self._ip_auth_path = ip_auth_path
        self._key_auth_path = key_auth_path

    def _build_url(self, path):
        return self._protocol + '://' + self._host + ':' + self._port + '/' + path

    def classifiers(self):
        url = self._build_url(self._classifier_path + 'info')
        r = requests.get(url)
        r.raise_for_status()
        return json.loads(r.content.decode())

    def classifier_classify(self, name, X, authkey=None):
        url = self._build_url(self._classifier_path + 'classify')
        if authkey:
            data = {'name': name, 'X': X, 'authkey': authkey}
        else:
            data = {'name': name, 'X': X}
        r = requests.post(url, data=data)
        r.raise_for_status()
        return json.loads(r.content.decode())

    def ip_info(self):
        url = self._build_url(self._ip_auth_path + 'info')
        r = requests.get(url)
        r.raise_for_status()
        return json.loads(r.content.decode())

    def key_info(self, authkey):
        url = self._build_url(self._key_auth_path + 'info')
        data = {'authkey': authkey}
        r = requests.post(url, data)
        r.raise_for_status()
        return json.loads(r.content.decode())

<%! import cherrypy %>
<%
scheme = cherrypy.request.scheme
name = cherrypy.request.local.name
port = cherrypy.request.local.port
%>
if __name__ == '__main__':
    protocol = '${scheme}'
    host = '${name}'
    port = ${port}
    classifier_path = '${classifier_path}'
    ip_auth_path = '${ip_auth_path}'
    key_auth_path = '${key_auth_path}'

    key = None
    # if you have an authkey
    # key = 'you_authkey_here'

    service_client = ServiceDemoClient(protocol, host, port, classifier_path, ip_auth_path, key_auth_path)

    classifiers = service_client.classifiers()

    test_texts = ['this is a text', 'this is another one']

    print()
    print('Documents to be labeled:', test_texts)
    for classifier in classifiers:
        print()
        print('Using classifier:', classifier)
        print()
        print('Assigned labels:', service_client.classifier_classify(classifier['name'], test_texts, authkey=key))

    print()
    print('IP requests stats:', service_client.ip_info())

    try:
        print()
        print('Key requests stats:', service_client.key_info(key))
    except HTTPError:
        print('Error: the key stats method works only with valid keys')