Authentication

For all calls, supply your API key. Sign up to obtain the key.

Our API supports both unencrypted (HTTP) and encrypted (HTTPS) protocols. However, for security reasons, we strongly encourage using only the encrypted version.

The API key should be supplied as either a request parameter user_key or in Authorization header.

Authorization: user_key <YOUR_API_KEY>

API operations

All API operations can perform analysis on supplied raw text or on text extracted from a given URL. Optionally, one can supply additional information which can make the result more precise. An example of such information would be the language of text or a particular text extractor for URL resources.

The supported types of analyses are:

• lemmatization ⟶ Finds out lemmata (basic forms) of all the words in the document.
• correction ⟶ Performs correction (diacritization) on all the words in the document.
• topic detection ⟶ Determines a topic of the document, e.g. finance or sports.
• sentiment analysis ⟶ Determines a sentiment of the document, i.e. how positive or negative the document is.
• named entity recognition ⟶ Finds named entities (like person, location, date etc.) mentioned the the document.

Encoding

The supplied text is expected to be in UTF-8 encoding, this is especially important for non-english texts.

Returned values

The API calls always return objects in serialized JSON format in UTF-8 encoding.

If any error occurs, the HTTP response code will be in the range 4xx (client-side error) or 5xx (server-side error). In this situation, the body of the response will contain information about the error in JSON format, with exception and message values.

URL limitations

All the requests are semantically GET. However, for longer texts, you may run into issues with URL length limit. Therefore, it's possible to always issue a POST request with all the parameters encoded as a JSON in the request body.

Example:

        POST /s1/sentiment
        Content-Type: application/json

        {"text":"There is no harm in being sometimes wrong - especially if one is promptly found out."}
    

This is equivalent to GET /s1/sentiment?text=There%20is%20no%20harm...

Request limitations

The API has other limitations concerning the size of the HTTP requests. The maximum allowed size of any POST request body is 512 KiB. For request with a URL resource, the maximum allowed number of extracted characters from each such resource is 100,000.

More information

The Interpretor Public Documentation