Working With Terms

The basic building blocks for performing semantic computations are the representations for single terms. Each Retina contains semantic representations (fingerprints) for a large number of terms, and this page describes how to retrieve these from the API. Furthermore we describe how to query the Retina for semantically similar terms, and retrieve a list of contexts in which a given term can occur.

REST API

The API endpoints related to term input are:

  • terms retrieve semantic representation for a term
  • terms/similar_terms get similar terms for a term
  • terms/contexts get contexts for a term

Terms

Under terms we can query the semantic spaces for its content. Try typing in a query term in the term input field on the interactive API documentation. In return you will get a Term object for a term in the Retina. The request URL for getting the semantic fingerprint of the term computer will look like this:

"http://api.cortical.io/rest/terms?retina_name=en_associative&term=computer&start_index=0&max_results=10&get_fingerprint=false"

The API describes the structure of the returned object (Response Class), in this case a Term object – see this example from the Quick Start section.

The same endpoint can be queried with a string including wildcard characters and will in this case return a number of matching term objects (in a list). The initial occurrence of a wildcard must be preceded by at least 3 characters. E.g.

  • app* is a valid string
  • ap* is not a valid string (the initial occurrence of the wildcard is not preceded by 3 characters)
  • app*e* is a valid string

Leaving the input field blank will list all terms in the Retina. There are also query parameters for selecting a range of the results to retrieve (start_index and max_results). If the get_fingerprint parameter is set to true, the Term object will also include the actual positions in the semantic space; these can be useful in your own semantic computations.

Similar Terms

Another functionality offered is to get similar terms for an input term. To do this, use the terms/similar_terms endpoint. The URL for this Rest call is:

"http://api.cortical.io/rest/terms/similar_terms?retina_name=en_associative&term=apple&start_index=0&max_results=10&pos_type=NOUN&get_fingerprint=false"

Note that the most similar term to the input term will always be itself. There are for the moment 2 Retinas to choose from (en_associative and en_synonymous) and the results are likely to be different when querying one or the other. In the URL above, please note that the call includes the query parameter pos_type=NOUN. This will make the Retina only return terms that can be nouns – more documentation for this can be found directly in the interactive API documentation. The query parameter context_id can be set to an index related to the contexts explained below. Only terms belonging to that context will then be returned.

Contexts

Using the semantic space we can decide a number of contexts that a term can belong to. For example the term apple can be understood as a fruit or an electronic device – depending on the context. Querying the contexts endpoint is done through this URL:

"http://api.cortical.io/rest/terms/contexts?retina_name=en_associative&term=apple&start_index=0&max_results=5&get_fingerprint=false"

The result would be a list of Context objects like these:

[
   {
     "context_label": "software",
     "fingerprint": {
       "positions": []
     },
     "context_id": 0
   },
   {
     "context_label": "fruit",
     "fingerprint": {
       "positions": []
     },
     "context_id": 1
   },
   {
     "context_label": "desktop",
     "fingerprint": {
       "positions": []
     },
     "context_id": 2
   },
   {
     "context_label": "iphone",
     "fingerprint": {
       "positions": []
     },
     "context_id": 3
   }
]

Each context is labeled with a context_id, which can be referred to from the /similar_terms endpoint as mentioned above. Each context_label is to be understood as a representative for the group of terms present in that context, and as such may not give an exhaustive explanation or be the most high level descriptor of the members of the class.

API Clients

The FullClient object available in the Java, Python, and JavaScript client libraries has the following methods for calling the terms endpoints:

  • getTerms
  • getSimilarTermsForTerm
  • getContextsForTerm