<%inherit file="public_basewithmenu.html"/> <%block name="head"> ${parent.head()}

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, an 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.

Name of the classifier:

Text to classify:

# 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')