SpringSense Meaning Recognition API

Overview

The SpringSense Meaning Recognition API provides a simple yet powerful way to integrate the SpringSense Meaning Recognition engine into your application or service.

Our Meaning Recognition engine is the fastest and most accurate noun-sense disambiguation technology in the world.

The API is now available on the Mashape API marketplace for your use, including a FREE usage tier.

The easiest way to think of the Meaning Recognition API, is “text in, disambiguated text out”.

The API is a RESTful JSON web-service. A simple GET request with the text to recognise leads to a response containing a simple JSON structure containing the three most likely recognised meanings for the text.

The API is now available for consumption through the Mashape API marketplace for your use, including a FREE usage tier. The Mashape console provides a simple user interface to try the API.

As a JSON based API, you may use any HTTP enabled mechanism to access the API. Any of your favorites will do such as  cURL, Ruby, Java and even client-side JavaScript.

SpringSense provides and supports open-source API bindings in Java and Ruby as well as other languages on the SpringSense GitHub page. These bindings can be used as is or as examples of using the API.

Also on our github repository is the ‘dumber downer’ Twitter client, which automatically either dumbs-down or ‘dumbs-up’ tweets as an example use of the API. Below we’ll explore using the raw API using cURL.

Example use

The following example can be run with cURL from the command-line once you receive your API access. Hopefully, this will allow you to understand the API input and output. Note: For readability, we’ve excluded the Mashape authentication headers from the command line.

curl https://springsense.p.mashape.com/disambiguate?body=military+vet

The response:

[
   {
      "terms":[
         {
            "lemma":"military",
            "word":"military",
            "POS":"JJ",
            "meanings":[
               {
                  "definition":"the military forces of a nation",
                  "meaning":"military_n_01"
               },
               {
                  "definition":"the military forces of a nation",
                  "meaning":"military_n_01"
               },
               {
                  "definition":"the discipline dealing with the principles of warfare",
                  "meaning":"military_science_n_01"
               }
            ]
         },
         {
            “lemma”:“vet”,
            “word”:“vet”,
            “POS”:“NN”,
            “meanings”:[
               {
                  "definition":"a person who has served in the armed forces",
                  "meaning":"veteran_n_02"
               },
               {
                  "definition":"a doctor who practices veterinary medicine",
                  "meaning":"veterinarian_n_01"
               },
               {
                  "definition":"a doctor who practices veterinary medicine",
                  "meaning":"veterinarian_n_01"
               }
            ]
         }
      ],
      “scores”:[
         0.45197218499643271,
         0.281141839702645,
         0.26688597530092228
      ]
   }
]

What we’re seeing above is that the SpringSense Meaning Recognition API has analysed the text ‘military vet’, and determined that the most likely meaning is ‘military veteran’ vs. the less likely ‘military veterinarian’ or ‘military_science veterinarian’.

The API output is divided into two sections:

The first section, the “terms”, holds an ordered list of the terms that were identified in the original text in the order that they appeared in the text.

Each term entry contains the lemma form of the term, the term itself, a part of speech (POS) tag of that term, as determined by SpringSense, and an ordered collection of three possible meanings for that term in order of decreasing probability.

The Part of Speech tags used by SpringSense are the same as those used in the Penn Treebank Project.

Each meaning is given as a definition from the WordNet lexical database of English and a meaning key in the same database.

The second section of the API result, the “scores”, holds an ordered collection of the probabilities of each meaning of each term, where the order corresponds to the order of meanings for each term.

For example, the first most-likely meaning is 45% likely, compared with only 28% and 26% for the 2nd and 3rd likely meanings respectively.