Meaningtool API Documentation

An API for your applications to make full use of Meaningtool Category Trees capabilities as a RESTful Web Service is available. This API handles different response formats such as JSON, XML, and JavaScript.

The API mostly conforms the HTTP/1.1 protocol as defined in RFC 2616. Exceptions are explained.

Index

Meaningtool Results
Making HTTP Requests
HTTP Responses
API Methods
- Categories
- Tags
Errors Reference

Meaningtool Results

A Meaningtool Result contains the actual resource you requested, decoupled from a representation.

A Result will always contain the following keys and values:

status : string

A status indicator: ok or error.

errcode : string

When status is error, this value will be a unique identifier for the error scenario, otherwise this will be an empty string. You can lookup what does this error means in the Errors Reference.

message : string

Detailed and human-readable message about what just happened (E.g, wrong tree_key or successfully categorized).

data : object

The actual requested resource.

Making HTTP Requests

Every Request considers the following important parameters at least:

HTTP Request Path ending

The last characters of the HTTP Request Path, preceded by a dot (.), determine the response format. E.g, if there were a resource at http://foo.bar/hello, it could be retrieved as XML from http://foo.bar/hello.xml.

Valid values (one MUST be provided):

json

The Result will be formated as JSON. This is the default if a value is not given.

js

The body of the Response will be a piece of JavaScript code calling a function specified by the HTTP Request argument js_callback value, using the actual Result of the request (as a JavaScript object, formated the same as the JSON representation would) as the first and only parameter in this call. This is only useful if you are using the API from JavaScript.

xml

The Result will be formated as XML.

If the representation you ask for is not supported, then the server responds with HTTP Status Code 404 and an empty HTTP Response body.

HTTP Request Header Accept-Charset

Behaves as defined in RFC 2616, sec 14.2 except Quality Factors (q) are ignored.

If nothing is specified, then UTF-8 is assumed.

If the charset you ask for is not supported or can't encode the Result, then the server responds with HTTP Status Code 406 and an error Result representation.

HTTP Request Header Content-Type

Behaves as defined in RFC 2616, sec 14.17. The mime type specified must be application/x-www-form-urlencoded (this is usually the default for HTTP clients).

You can specify the value of the argument charset in this header to change the charset of the HTTP Request contents, otherwise charset=UTF-8 will be assumed.

HTTP Parameter input_language

This value determines the language of any text Meaningtool will try to read from the input text. If you don't specify this, Meaningtool will try to guess the language.

HTTP Responses

Each HTTP Response exposes a representation of a Meaningtool Result.

The representation of this Result is formatted as requested and sent back to the client along with the corresponding HTTP Status Code and HTTP Response Headers.

JSON Representation

The Content-Type HTTP Response Header for a JSON formated Response will be: application/json.

Example HTTP Response body:

{
  "status": "ok",
  "errcode": "",
  "message": "3 categories found",
  "data": {
    "categories": [
      { "score": 0.75, "name": "Nature/Animals" },
      { "score": 0.5, "name": "Human body" },
      { "score": 0.40000000000000002, "name": "Physics" }
    ],
  }
}

JavaScript Representation

The Content-Type HTTP Response Header for a JavaScript formated Response will be: application/javascript.

Example HTTP Response body when HTTP Request argument js_callback=foo:

foo({
  "status": "ok",
  "errcode": "",
  "message": "3 categories found",
  "data": {
    "categories": [
      { "score": 0.75, "name": "Nature/Animals" },
      { "score": 0.5, "name": "Human body" },
      { "score": 0.40000000000000002, "name": "Physics" }
    ],
  }
});

XML Representation

The Content-Type HTTP Response Header for a XML formated Response will be: application/xml.

Example HTTP Response body:

<?xml version="1.0" encoding="UTF-8"?>
<resource>
  <status>ok</status>
  <errcode></errcode>
  <message>3 categories found</message>
  <data>
    <categories>
      <category score="0.75" name="Nature/Animals" />
      <category score="0.5" name="Human body" />
      <category score="0.40000000000000002" name="Physics" />
    </categories>
  </data>
</resource>

API Methods

All the API methods explained here share the same common base URL: http://ws.meaningtool.com/0.1/trees/<tree_key>, where tree_key is a Meaningtool Category Tree Key.

Every request made to the Meaningtool API is related to a Meaningtool Category Tree which alters the behaviour of the processing involved to get a Result. You can set up this Category Tree within your Meaningtool Account, or just pick one of the defaults Meaningtool provides.

The value of tree_key should be the unique identifier for a Meaningtool Category Tree: The Category Tree Key. You can find this key in Tree Directory for a public tree or in My Trees for a custom tree.

Example base URL when tree_key is 498f4586-a314-4817-8f6e-e45728c8dc0f:

http://ws.meaningtool.com/0.1/trees/498f4586-a314-4817-8f6e-e45728c8dc0f

On error, the HTTP Response Status Code and Result message will explain the situation.

Categories

This method returns a set of categories resolved from a particular Meaningtool Category Tree for some text input.

HTTP Method

GET / POST

Note: POST is also accepted here, since sometimes GET won't be enough (e.g, very long GET query strings are not supported by all web servers and proxies).

URL

http://ws.meaningtool.com/0.1/trees/<tree_key>/categories

HTTP Request parameters (query string)

api_key

The application key obtained after you signed up in meaningtool.com.

source

Determines where and how Meaningtool should read the text input. Possible values are:

text: The input text is sent along with this request, in another parameter named input.
url: The input text is available at the URL specified in another parameter named input.
html: The input text is sent along with this request, as an HTML document in another parameter named input.

input

Input data to be categorized. The meaning of this value is determined by the value specified in another parameter named source.

url_hint

When the value of another parameter named source is text, providing the URL from where you fetched that text here could help in the categorization of that input. Otherwise, this value is ignored.

additionals

A comma (,) separated list of additional data to return along with the categories for the input text. Possible values are:

top-terms: Include a list of overall top terms found in the text that where relevant to the categorization.
classifiers: Include a list of the classifiers in the Category Tree that were involved in this categorization together with its overall score in the categorization.
classifiers-top-terms: Include a list of top terms found in each classifier that appeared in the input text together with its score within the classifier.

Example JSON representation of a Result on success (with additionals=top-terms,classifiers,classifiers-top-terms):

{
  "status": "ok",
  "errcode": "",
  "message": "3 categories found",
  "data": {
    "categories": [
      { "score": 0.75, "name": "Nature/Animals" },
      { "score": 0.5, "name": "Human body" },
      { "score": 0.40000000000000002, "name": "Physics" }
    ],
    "top-terms": [
      { "name": "face" },
      { "name": "muscle" },
      { "name": "humanenvironment" },
      { "name": "body" },
      { "name": "stong" }
    ],
    "classifiers": [
      {
        "name": "Digg Environment",
        "score": 0.59999999999999998,
        "top-terms": [
          { "score": 0.40000000000000002, "name": "face" },
          { "score": 0.29999999999999999, "name": "muscle" },
          { "score": 0.20000000000000001, "name": "human" },
          { "score": 0.10000000000000001, "name": "strong" }
        ]
      },
      {
        "name": "Slashdot.org Science",
        "score": 0.5,
        "top-terms": [
          { "score": 0.29999999999999999, "name": "muscle" },
          { "score": 0.20000000000000001, "name": "environment" },
          { "score": 0.10000000000000001, "name": "body" }
        ]
      }
    ]
  }
}

Example XML representation of a Result on success (with additionals=top-terms,classifiers,classifiers-top-terms):

<?xml version="1.0" encoding="UTF-8"?>
<resource>
  <status>ok</status>
  <errcode></errcode>
  <message>3 categories found</message>
  <data>
    <categories>
      <category score="0.75" name="Nature/Animals" />
      <category score="0.5" name="Human body" />
      <category score="0.40000000000000002" name="Physics" />
    </categories>
    <top-terms>
      <term name="face" />
      <term name="muscle" />
      <term name="humanenvironment" />
      <term name="body" />
      <term name="stong" />
    </top-terms>
    <classifiers>
      <classifier name="Digg Environment" score="0.59999999999999998">
        <top-terms>
          <term name="face" score="0.40000000000000002" />
          <term name="muscle" score="0.29999999999999999" />
          <term name="human" score="0.20000000000000001" />
          <term name="strong" score="0.10000000000000001" />
        </top-terms>
      </classifier>
      <classifier name="Slashdot.org Science" score="0.5">
        <top-terms>
          <term name="muscle" score="0.29999999999999999" />
          <term name="environment" score="0.20000000000000001" />
          <term name="body" score="0.10000000000000001" />
        </top-terms>
      </classifier>
    </classifiers>
  </data>
</resource>

Errors Reference

"OK" : EOK: OK.
"InvalidArgumentsError" : EINVAL: Invalid arguments.
"BadFormatRequestedError" : EBADFORMAT: Bad format requested.
"InternalError" : EINTERNAL: Internal error.
"UrlClientError": EURLCLIENT: Connection problem while fetching the input when it is an url (40X error code)
"UrlDestinationServerError": EURLDESTINATIONSERVER: Destination server problem while fetching the input when it is an url (50X error code)
"ContractNotActive": ECONTRACT: The user contract has changed and hasn't been activated.
"LimitsExceeded": ELIMITS: There were too many hits taking into account the user contract.
"UserKeyInvalid": EINVALIDUSER: A user with the specified API key doesn't exist.
"CategoryTreeNotFound": ENOCATTREE: A category tree with the specified Tree key doesn't exist.
"CategoryKeyInvalid": EINVALIDCATEGORYTREE: The category tree associated with the given Tree key doesn't belong to the user and isn't public.
"NoTextScoringError": ENOTEXTSCORING: There isn't enought text in the input to categorize.
"CannotDetectLanguageScoringError": ECANTDETECTLANGUAGE: It can't detect the language of the input.
"NoClassifiersScoringError": ENOCLASSIFIERS: No classifiers of the category tree match the input.

Sign up to create your own AI