Use the API from your code

To interact with the API, the client code must send a POST request to the API's endpoint on Mashape or 3Scale, and receive a response object.


URL (Mashape) (3Scale)


  • X-Mashape-Key (for Mashape users): a string containing a 50-character Mashape access key. The key can be found on your Mashape application page or in the example code next to the test console.
  • X-Scale-Key (for 3Scale users): a string containing a 3Scale access key, can be found on the Developer Portal, under "API Credentials".


  • text: the string to be analyzed. Optionally, multiple small documents can be included into string, each enclosed into a "doc" tag with an "id" attribute holding a string value unique in the current request. There is a 10,000 character limit on the size of the text posted in one request. If the size of the text is over the limit, but smaller than 12,000 characters, it will be truncated to 10,000 characters and a warning added to the response. If the text is larger than 12,000 characters, an error response will be returned.
  • domain: the string indicating the domain of the text. The value can be "general" for the general-language domain, the name of any of the prebuilt domains, or the name of your custom domain.
  • terms: 0 (default) or 1, if terms should be extracted. Terms are single words and multi-word phrases expressing key notions found in the text.
  • sentiment: 0 (default) or 1, if sentiment should be detected. Sentiment is analyzed in terms of positive, negative and neutral labels.
  • categories: 0 (default) or 1, if categories of terms should be detected. Categories are not detected, if the domain value is "general".
  • annotate: 0 (default) or 1, if the response should include the original input string with XML annotations containing the analysis.

Here is an example client code in Python:

import urllib, urllib2, json
from pprint import pprint

URL = ""
text = "The food was great, but the service was slow."
params = {'text': text, 'domain': 'retail', 'terms': 1, 'categories': 1, 'sentiment': 1, 'annotate': 1}
headers = {'X-Mashape-Key': YOUR_MASHAPE_KEY}

opener = urllib2.build_opener(urllib2.HTTPHandler)
request = urllib2.Request(URL, urllib.urlencode(params), headers=headers)
response =

data = json.loads(


The response contains a JSON string with the results. The top-level field in the JSON object that contains the analysis is docs, containing a list of objects, each corresponding to a submitted document. The fields in a document object correspond to the requested types of analysis and can be:

  • doc_id: the id of the document as it was included into the request; "0" if a single document was submitted.
  • terms: a list of term object. Each term object contains:
    • id: an id of the term, to which different surface forms of the term (singular and plural forms, case variants, etc) are mapped.
    • count: the number of time the term appeared in the document
    • term: a normalized form of the term
    • sentiment: an object containing values for positive ("pos"), negative ("neg") and neutral ("neu") sentiment associated with the term, calculated for the whole document. The values are doubles that range between 0.0 and 100.0. The field is included, if the "sentiment" parameter in the request was set.
  • categories: an object where fields correspond to topical categories, each value in the field is a sentiment object, similar to the one included for a term, i.e., containing values ranging between 0.0 and 100.0 and expressing positive, negative and neutral sentiment associated with the category in the whole document. The field is included into the response if the "domain" parameter in the request was set.
  • sentiment: a sentiment object describing overall sentiment in the document.
  • text: an XML string with the original document, where detected sentiment, terms and categories are annotated with in the document: the doc tag encloses one document, the s tag encloses one sentence, the c tag encloses a clause, the k tag encloses a term. The field is included into the response if the "annotate" parameter in the request was set.

Any warning messages are included into the "warning" field are the top level of the response object.

Below is an example of a response.

{"docs": [{"categories": {"ambience": {"sentiment": {"neg": 0, "neu": 0, "pos": 0}},
                            "food": {"sentiment": {"neg": 0, "neu": 0, "pos": 100.0}},
                            "location": {"sentiment": {"neg": 0, "neu": 0, "pos": 0}},
                            "parking": {"sentiment": {"neg": 0, "neu": 0, "pos": 0}},
                            "price": {"sentiment": {"neg": 0, "neu": 0, "pos": 0}},
                            "service": {"sentiment": {"neg": 100.0, "neu": 0, "pos": 0}}},
            "doc_id": "0",
            "sentiment": {"neg": 50.0, "neu": 0.0, "pos": 50.0},
            "terms": [{"count": 1,
                        "id": "95734a603c1b3a17b0974c51c07f6f355e90eb0a",
                        "sentiment": {"neg": 0.0, "neu": 0.0, "pos": 100.0},
                        "term": "food"},
                       {"count": 1,
                        "id": "c5a6a8018f75e72011c3ac8f7cadf952799a1985",
                        "sentiment": {"neg": 100.0, "neu": 0.0, "pos": 0.0},
                        "term": "slow"},
                       {"count": 1,
                        "id": "f250ca1f36d76a596b08dbc2146d4780ea5348b2",
                        "sentiment": {"neg": 100.0, "neu": 0.0, "pos": 0.0},
                        "term": "service"}],
            "text": "<doc><s id=\"0\"><c class=\"food pos\" id=\"0\">The <k id=\"95734a603c1b3a17b0974c51c07f6f355e90eb0a\" class=\"term\">food</k> was great</c>, <c class=\"service neg\" id=\"1\">but the <k id=\"f250ca1f36d76a596b08dbc2146d4780ea5348b2\" class=\"term\">service</k> was <k id=\"c5a6a8018f75e72011c3ac8f7cadf952799a1985\" class=\"term\">slow</k>.</c></s></doc>"}],
 "warnings": []}

 Feel free to use example clients in Java, Python, Ruby, PHP, R, Node.js, C#.