.. highlight:: java


.. _label-classification:

##############
Classification
##############

Currently we offer a single classification endpoint:

* ``/classification/create_category_filter``

This endpoint allows the user to create category filters, simply and easily, using only a small number of example texts. 
The newly created category filters can then be used as part of a classification process, where items to be classified can be compared against the category filters 
using our ``/compare`` and/or ``/compare/bulk`` endpoints (which you can see in our |swagger_api|). 
See our :ref:`similarity metrics`<label-similarity-metrics>` guide for information on how to interpret the output from the compare endpoints.


.. |swagger_api| raw:: html

   <a href="http://api.cortical.io" target="_blank">interactive API documentation</a>


REST API
########

The ``create_category_filter`` endpoint is implemented as a ``POST`` call, where the **FilterTrainingObject** containing the training examples is attached to an ``HTTP-Header``.
For example, using ``curl``, a category filter can be obtained in the following manner (all on one line):: 

   curl -k -X POST -H "api-key: yourApiKey" -H "Content-Type: application/json" "http://api.cortical.io/rest/classify/create_category_filter?retina_name=en_associative&filter_name=shoes" -d @yourInputItems.txt

The contents of the file ``yourInputItems.txt`` must conform to the json format for a **FilterTrainingObject** as in the example below::

   {
      "positiveExamples" : [
         { "text" : "Shoe with a lining to help keep your feet dry and comfortable on wet terrain." },
         { "text" : "running shoes providing protective cushioning." }
      ],
      "negativeExamples" : [ 
          { "text" : "The most comfortable socks for your feet."}, 
          { "text" : "6 feet USB cable basic white"}
      ]
   }

Note that negative examples are not mandatory. The following is an example of a **FilterTrainingObject** containing only positive examples::

      {
         "positiveExamples" : [
            { "text" : "Shoe with a lining to help keep your feet dry and comfortable on wet terrain." },
            { "text" : "running shoes providing protective cushioning." }
         ]
      }


API Clients
###########

The ``FullClient`` object available in the `Java <https://github.com/cortical-io/retina-api-java-sdk>`_, 
`Python <https://github.com/cortical-io/retina-sdk.py>`_, and
`JavaScript <https://github.com/cortical-io/RetinaSDK.js>`_ client libraries has the following methods for calling the ``classification`` endpoints:

* ``createCategoryFilter``