Quick Start

This page is intended to jump-start you on using the Retina. The best place to start is by having a look at our interactive API documentation (also see below), where you can explore and try out the functionality of the Retina.

Having found out what functionality you would like to use, you would probably like to access the API in a programmatic way. For this you will need to sign up and get an api-key, which is needed in every call to the service. We recommend using a client library, which allows access to the service without having to bother with the HTTP requests. Below, we give a simple example of how to access the API by working with Java objects.


The API lets you convert written material (whether terms, sentences or entire texts) into a semantic representation, which allows you, for example, to compare the content of these entities on the semantic level. The interactive API documentation describes the functionality of each of the methods available in the API, and lets you try out the functionality immediately in a GUI environment.

The basic unit that carries a semantic representation in the Retina is a term, and the Retina contains semantic representations for a huge number of terms. Let’s try to retrieve the semantic fingerprint of the term computer from the API. If you browse to the interactive API documentation, and click the link to the Term page, you can expand the functions available for term input. Having expanded the /terms endpoint, you should now see a screen similar to this:


Feel free to read the documentation of the single input fields, or just leave everything with its defaults, and type in computer next to term. Change the value of the get_fingerprint drop down menu to true, and click Try it out!. The response of the call will now be displayed in a pane. The response is a list of Term objects (in this case only one item). The attributes of a Term object are described in the interface (see screen shot above ). The content of the Fingerprint object inside the Term object contains the semantic representation of the term computer.

Also, the page now displays the Request URL:


You could use this URL from within your code by including your api-key, for example by using cURL:

curl -k -X GET -H "api-key: yourApiKey" "http://api.cortical.io/rest/terms?retina_name=en_associative&term=computer&start_index=0&max_results=10&get_fingerprint=true"

API Clients

We offer clients in order to access the API in Java, Python, and JavaScript. The clients let the user access the Rest API through method calls, and get objects back in return.

The clients all have a similar structure. The FullClient object has methods for accessing all endpoints. We will list a few examples here on how to use the FullClient using the Java client. The FullClient has the same methods in the Java, Python and JavaScript libraries as well as similar return types.

Each client also contains a minimalistic LiteClient, that accesses only the most frequently used endpoints, and returns simple data types. Please visit the individual repositories through the links above for more details about the simple clients.

Initial Setup

To access the API, you will need an instance of the FullClient. The constructor requires an API key which you can obtain from the main Cortical.io website The constructor also lets you define which retina to use:

FullClient client = new FullClient(apiKey, "en_associative");

Terms Api

With the terms Api you can, for example, retrieve similar nouns for the term tiger like this:

List<Term> similarTerms = client.getSimilarTermsForTerm("tiger", -1, PosType.NOUN, 0, 20, true);

The API returns a list of Term objects. The first term in the list looks like this:

class Term {
    df: 7.107671905701706E-4
    pos_types: [NOUN]
    score: 164.0
    term: tiger
    fingerprint: class Fingerprint {
        positions: [78, 319, 380, 508, 641, 703, 739, 740, 742, 880, 939, 940, 1006, 1122, 1292,
                    1350, 1402, 1598, 1773, 1774, 1898, 1901, 1944, 1945, 2020, 2033, 2060, 2071,
                    2157, 2282, 2288, 2289, 2290, 2309, 2412, 2536, 2540, 2665, 2666, 2750, 2751,
                    2792, 2793, 2878, 2912, 2920, 3040, 3041, 3046, 3047, 3136, 3189, 3193, 3298,
                    3299, 3300, 3316, 3395, 3424, 3444, 3569, 3576, 3697, 3698, 3702, 3825, 3826,
                    3827, 3828, 3955, 4083, 4186, 4317, 4324, 4457, 4578, 4593, 4732, 4757, 4956,
                    4969, 5060, 5183, 5291, 5323, 5365, 5487, 5501, 5567, 5668, 5686, 5687, 5692,
                    5693, 5820, 5821, 5822, 5948, 6044, 6052, 6063, 6176, 6283, 6543, 6795, 6796,
                    7174, 7322, 7451, 7453, 7545, 7606, 8218, 8304, 8348, 8737, 8894, 8895, 8965,
                    9074, 9121, 9360, 9935, 10117, 10118, 10123, 10124, 10255, 10284, 10299, 10323,
                    10755, 10767, 11025, 11187, 11954, 11980, 12337, 13034, 13310, 13378, 13423,
                    13560, 14661, 14698, 14916, 14971, 14973, 15094, 15099, 15228, 15229, 15335,
                    15336, 15337, 15462, 15463, 15464, 15465, 15467, 15589, 15590, 15591, 15717]

The fields of the Term object include the document frequency of the term (df); A list of part of speech tags that the term can have; A score related to the similarity with the query term (the number of overlapping positions in common with the fingerprint of the query term); A string representation of the term; And finally a Fingerprint object with the actual positions of the term. The Term object has getters to retrieve these values.

Expressions Api

The semantic fingerprint is the basic unit within the Retina API. A text or a term can be resolved into a fingerprint using the API. Fingerprints can also be combined in expressions, and the /expressions endpoints expect input in our expression language. This is explained in more detail here. Expressions are essentially json strings with reserved keys: term, text, and positions.


In the Java client, this json formatting is abstracted away, by letting the user work with Term and Text objects. The client offers a static helper class io.cortical.retina.model.ExpressionFactory which has convenience methods for creating Term and Text objects as well as methods (and, or, sub, and, xor) to assist in building expressions.

For instance, to create a Term object for the term brain you can use the static method term:

Term term = ExpressionFactory.term("brain");

And to AND two terms together you can use the ExpressionFactory.and static method. This method returns an Expression (an object of type ExpressionModel).

ExpressionModel andExpression = ExpressionFactory.and(ExpressionFactory.term("brain"), ExpressionFactory.term("cortex"));

Expression operators can take multiple input types. For instance, you can OR a Term object with a Text object. We can now get the similar terms for such an expression:

ExpressionModel orExpression = ExpressionFactory.or(ExpressionFactory.term("brain"), ExpressionFactory.text("a region of the cerebral cortex"));
List<Term> terms = client.getSimilarTermsForExpression(orExpression);

(In reality the Expression operation is performed on the semantic fingerprints of the respective input types).

Python and JavaScript

In Python the client expects json strings, and in JavaScript json objects. The previous example would look like this in Python:

orExpression = {"or": [{"term": "brain"}, {"text": "a region of the cerebral cortex"}]}
terms = client.getSimilarTermsForExpression(json.dumps(orExpression))

The actual string that is sent to the API is in all cases:

{"or": [{"term": "brain"}, {"text": "a region of the cerebral cortex"}]}

Compare Api

Let’s try to compare the semantic similarity of the term painter and a short description of Gustav Klimt. For this we need to call the compare method on the client (note: the example below is for the Java client):

String inputText = "Gustav Klimt (July 14, 1862 – February 6, 1918) was an Austrian symbolist painter and one "
        + "of the most prominent members of the Vienna Secession movement. Klimt is noted for his paintings, "
        + "murals, sketches, and other objets d'art. Klimt's primary subject was the female body;[1] "
        + "his works are marked by a frank eroticism.[2]";
Metric metric = client.compare(new Term("painter"), new Text(inputText));

In Python and Javscript we will need to encode the input as a json list of a two elements. The example below shows how this can be done in Python.:

expList = [{"term": "painter"}, {"text": "Gustav Klimt (July 14, 1862 – February 6, 1918) was an Austrian symbolist painter and one of the most prominent members of the Vienna Secession movement."}]
metric = client.compare(json.dumps(expList))

The output is a Metric object, containing the following fields (note: the structure of all response classes is described directly within the interactive API documentation):

class Metric {
    cosineSimilarity: 0.34935777200667767
    euclideanDistance: 0.6797804208600183
    jaccardDistance: 0.809368191721133
    overlappingAll: 175
    overlappingLeftRight: 0.5335365853658537
    overlappingRightLeft: 0.22875816993464052
    sizeLeft: 328
    sizeRight: 765
    weightedScoring: 56.1925405151255

Note that the similarity measures increase with similarity, whereas the distances decrease according to similarity. For more information regarding similarity measures please see: the similarity metrics guide.